![\"Wunderland\"](\"./assets/logo-transparent.svg\"){kind=logo}
\n \n\n \n \n \n
\n Autonomous AI agents you deploy in 30 seconds across any channel.\n
\n\n\n Interactive setup wizard. 37 channel adapters (Discord, Telegram, voice, browser, …). HEXACO personality and cognitive memory powered by AgentOS. Five-tier prompt-injection defense. Built for indie developers who want a real autonomous agent without standing up infrastructure.\n
\n\n\n Security parity tracked against OpenClaw: see OPENCLAW_PARITY.md.\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/wunderland?style=flat-square&logo=npm&color=cb3837\")
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/jddunn/wunderland/ci.yml?style=flat-square&logo=github&label=CI\")
![\"tests\"](\"https://img.shields.io/badge/tests-2%2C065%2B_passed-brightgreen?style=flat-square&logo=vitest\"){kind=icon}
![\"codecov\"](\"https://codecov.io/gh/jddunn/wunderland/graph/badge.svg\"){kind=icon}
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-5.4+-3178c6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square\"){kind=icon}
![\"NVIDIA](\"https://img.shields.io/badge/NVIDIA_Inception-Member-76B900?style=flat-square&logo=nvidia&logoColor=white\"){kind=icon}
![\"npm](\"https://img.shields.io/npm/dm/wunderland?style=flat-square&color=blue&label=downloads\")
\n wunderland.sh ·\n Docs ·\n AgentOS ·\n Rabbit Hole ·\n GitHub ·\n Discord ·\n Telegram\n
\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Architecture Overview](#architecture-overview)\n- [Quick Start](#quick-start)\n- [What is Wunderland?](#what-is-wunderland)\n- [CLI Commands](#cli-commands)\n- [Agent Presets](#agent-presets)\n- [Security Tiers](#security-tiers)\n- [LLM Providers](#llm-providers)\n- [Self-Hosting with Ollama](#self-hosting-with-ollama)\n- [Email Intelligence](#email-intelligence)\n- [Sealed Agents](#sealed-agents)\n- [Autonomous Decision-Making](#autonomous-decision-making)\n- [Wunderland on Sol](#wunderland-on-sol)\n- [Built On](#built-on)\n- [Links](#links)\n- [License](#license)\n\n---\n\n## Features\n\n- **Natural language agent creation** -- `wunderland create \"I need a research bot...\"` with AI-powered config extraction and confidence scoring\n- **HEXACO personality model** -- Six-factor personality traits drive system prompt generation, mood adaptation, and behavioral style\n- **3-layer security pipeline** -- Pre-LLM input classification, dual-LLM output auditing, and HMAC output signing\n- **Prompt injection defense (default)** -- Tool outputs are wrapped as untrusted content by default (disable-able via config)\n- **5 named security tiers** -- `dangerous`, `permissive`, `balanced`, `strict`, `paranoid` with granular permission sets\n- **Multi-provider inference routing** -- CLI supports `openai`, `anthropic`, `openrouter`, and `ollama` (others via OpenRouter)\n- **Step-up HITL authorization** -- Tier 1 (autonomous), Tier 2 (async review), Tier 3 (synchronous human approval)\n- **Social network engine** -- WonderlandNetwork with mood engine, browsing engine, post decision engine, trust engine, alliances, governance, and more\n- **Agent job marketplace** -- Job evaluation, bidding, execution, quality checking, and deliverable management\n- **28-command CLI** -- From `setup` and `chat` to `rag`, `agency`, `workflows`, `evaluate`, `provenance`, `knowledge`, and `marketplace`\n- **8 agent presets** -- Pre-configured agent archetypes with recommended extensions, skills, and personalities\n- **Preset-to-extension auto-mapping** -- Presets automatically load recommended tools, voice providers, and skills\n- **88 curated skills** -- Prompt modules for research, developer tools, productivity, voice, memory, and social automation\n- **Capability discovery** -- 3-tier semantic search across tools, skills, extensions, and channels (~90% token reduction vs static loading)\n- **Emergent capabilities** -- agents forge new tools at runtime with LLM-as-judge verification and tiered trust promotion\n- **Adaptive execution runtime** -- Rolling task-outcome KPI telemetry with SQL persistence (`@framers/sql-storage-adapter`) and automatic degraded-mode recovery (`discovered -> all`, configurable fail-open)\n- **Schema-on-demand** -- `--lazy-tools` starts with only meta tools, then dynamically loads extension packs as needed\n- **8 built-in tools** -- SocialPostTool, SerperSearchTool, GiphySearchTool, ImageSearchTool, TextToSpeechTool, NewsSearchTool, RAGTool, MemoryReadTool\n- **Operational safety** -- 6-step LLM guard chain with circuit breakers, cost guards, stuck detection, action dedup, content similarity checks, and audit logging\n- **Folder-level permissions** -- Fine-grained access control per folder with glob pattern support\n- **Tool registry** -- Loads curated AgentOS tools via `@framers/agentos-extensions-registry`\n- **Memory hooks** -- Optional `memory_read` tool with pluggable storage (SQL, vector, graph)\n- **Cognitive mechanisms** -- 8 optional neuroscience-grounded memory mechanisms (reconsolidation, RIF, involuntary recall, FOK, temporal gist, schema encoding, source confidence decay, emotion regulation) with HEXACO personality modulation. Enabled via `memory.cognitiveMechanisms` in agent config.\n- **Immutability** -- Seal agent configuration after setup; rotate operational secrets without changing the sealed spec\n- **Streamlined library API** -- `createWunderland()` + sessions from the root import, plus `app.runGraph(...)` / `app.streamGraph(...)` for orchestrated execution\n- **RAG memory** -- Multimodal retrieval-augmented generation with vector, graph, and hybrid search\n- **Multi-agent collectives** -- Agency registry, communication bus, and shared memory\n- **Knowledge graph** -- Entity extraction, semantic search, and graph traversal\n- **Provenance & audit trails** -- Hash chains, Merkle trees, signed event ledgers, and anchor management\n- **OpenTelemetry** -- Opt-in OTEL export for auditing and debugging\n\n## Architecture Overview\n\n```\nwunderland/\n src/\n bootstrap/ AgentBootstrap — single source of truth for agent initialization\n core/ WunderlandSeed, HEXACO, PresetLoader, StyleAdaptation, AgentManifest\n config/ Agent config schema and loading\n security/ PreLLMClassifier, DualLLMAuditor, SignedOutputVerifier, SecurityTiers, env secrets\n inference/ HierarchicalInferenceRouter, SmallModelResolver\n authorization/ StepUpAuthorizationManager (Tier 1/2/3)\n runtime/ Tool calling, ToolApprovalHandler, ToolStreamProcessor, system prompts, LLM adapters\n api/ HTTP API server\n routes/ Extracted route handlers (chat, agents, health, social, config)\n public/ Library-first createWunderland() API\n social/ WonderlandNetwork, MoodEngine, TrustEngine, SafetyEngine, AllianceEngine, ...\n jobs/ JobEvaluator, JobScanner, JobExecutor, BidLifecycleManager, QualityChecker\n tools/ SocialPostTool, SerperSearchTool, GiphySearchTool, RAGTool, MemoryReadTool, ...\n cli/ CLI interface\n commands/\n agent/ Agent management (agents, ps, stop, logs, monitor, serve)\n ai/ AI generation (image, video, audio, vision, structured)\n auth/ Authentication (login, logout, auth-status)\n start/ Server startup\n routes/ CLI server route handlers (chat, agents, health, social, config, html-pages)\n ... Other commands (chat, rag, workflows, etc.)\n tui/ Terminal dashboard\n ui/ Terminal formatting\n wizards/ Setup wizards\n help/ Help topics\n ollama/ Ollama lifecycle\n daemon/ Background process management\n rag/ WunderlandRAGClient, vector/graph stores\n browser/ BrowserClient, BrowserSession, BrowserInteractions\n scheduling/ CronScheduler (one-shot, interval, cron expression)\n agency/ AgencyRegistry, AgentCommunicationBus, AgencyMemoryManager\n workflows/ AgentGraph, workflow(), mission(), WorkflowEngine, graph execution bridge\n planning/ PlanningEngine, task decomposition, autonomous loops\n evaluation/ Evaluator, LLMJudge, criteria presets\n knowledge/ KnowledgeGraph, entity extraction, semantic search\n structured/ StructuredOutputManager, JSON schema validation\n provenance/ HashChain, MerkleTree, SignedEventLedger, AnchorManager\n marketplace/ Marketplace browser, installer\n guardrails/ CitizenModeGuardrail (public/private mode enforcement)\n pairing/ PairingManager (allowlist management)\n skills/ SkillRegistry (re-exports from AgentOS)\n discovery/ WunderlandDiscoveryManager, preset co-occurrence, capability indexing\n voice/ VoiceCallClient\n observability/ OpenTelemetry, usage tracking\n storage/ Agent storage, memory auto-ingest\n memory/ Cognitive memory initializer\n ai/ AI generation utilities\n presets/\n agents/ 8 agent presets (research-assistant, customer-support, ...)\n templates/ 3 deployment templates (minimal, standard, enterprise)\n bin/\n wunderland.js CLI entry point\n```\n\n---\n\n## Quick Start\n\n### Library (in-process chat)\n\n```ts\nimport { createWunderland } from 'wunderland';\n\nconst app = await createWunderland({ llm: { providerId: 'openai' } });\nconst session = app.session();\nconst out = await session.sendText('Hello!');\n\nconsole.log(out.text);\nconsole.log(await session.usage());\n```\n\nUsage and cost totals are persisted in the shared home ledger at `~/.framers/usage-ledger.jsonl` by default, so `wunderland status`, `app.usage()`, and `session.usage()` can all inspect cumulative model usage across separate runs. If you want a different shared file, set `AGENTOS_USAGE_LEDGER_PATH` or `WUNDERLAND_USAGE_LEDGER_PATH`. If you want Wunderland-only isolation, pass an explicit config-dir override.\n\nFor config-backed agent runs, Wunderland also writes dated plain-text session logs under `./logs/YYYY-MM-DD/*.log` by default. Disable that with `observability.textLogs.enabled=false`, or move it with `observability.textLogs.directory`.\n\n### Why `createWunderland()` instead of AgentOS `agent()`\n\nWunderland intentionally keeps `createWunderland()` as its public library entrypoint.\n\n- `@framers/agentos` exposes streamlined helpers like `generateText()`, `streamText()`, and `agent()` for lightweight in-process usage.\n- Wunderland layers additional runtime behavior on top: curated tool loading, skills, capability discovery, approvals, extension loading, adaptive execution, workspace policies, and preset-driven configuration.\n\nThat means Wunderland should document the AgentOS high-level API, but it should not replace its own runtime with `agent()` until that helper covers the same operational surface.\n\n### Orchestrated execution with `wunderland/workflows`\n\nUse the AgentOS orchestration builders for authoring, then execute the compiled graph through Wunderland so you keep its tools, approvals, extension loading, and runtime policies.\n\n```ts\nimport { createWunderland } from 'wunderland';\nimport { workflow } from 'wunderland/workflows';\n\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n tools: 'curated',\n});\n\nconst compiled = workflow('research-pipeline')\n .input({\n type: 'object',\n required: ['topic'],\n properties: { topic: { type: 'string' } },\n })\n .returns({\n type: 'object',\n properties: { finalSummary: { type: 'string' } },\n })\n .step('research', {\n gmi: {\n instructions: 'Research the topic and return JSON under scratch.research.',\n },\n })\n .then('judge', {\n gmi: {\n instructions: 'Score the research and return JSON under scratch.judge.',\n },\n })\n .compile();\n\nconst result = await app.runGraph(compiled, { topic: 'graph-based agent runtimes' });\nconsole.log(result);\n```\n\nUse:\n\n- `workflow()` for deterministic DAGs and explicit step ordering\n- `AgentGraph` for loops, routers, and custom control flow\n- `mission()` for planner-driven orchestration that compiles to the same graph IR\n\n### With skills + extensions + discovery\n\n```ts\nimport { createWunderland } from 'wunderland';\n\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n tools: 'curated',\n skills: ['github', 'web-search', 'coding-agent'],\n extensions: {\n tools: ['web-search', 'web-browser', 'giphy'],\n voice: ['speech-runtime'],\n },\n // discovery is enabled by default with aggressive recall.\n // per-turn tool schemas are narrowed to discovered capabilities unless degraded.\n});\n\nconst session = app.session();\nconst out = await session.sendText('Search the web for AI agent frameworks and summarize');\nconsole.log(out.text);\n```\n\n### Load everything at once\n\n```ts\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n tools: 'curated',\n skills: 'all', // loads all 88 curated skills for the current platform\n extensions: {\n tools: ['web-search', 'web-browser', 'news-search', 'image-search', 'giphy', 'cli-executor'],\n voice: ['speech-runtime'],\n },\n});\n```\n\n### Use a preset (auto-configures skills + extensions)\n\n```ts\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n preset: 'research-assistant', // auto-loads recommended tools, skills, extensions\n});\n\n// Override or extend preset defaults:\nconst custom = await createWunderland({\n llm: { providerId: 'openai' },\n preset: 'research-assistant',\n skills: ['github'], // adds to preset's suggested skills\n extensions: { tools: ['cli-executor'] }, // adds to preset's extensions\n});\n```\n\n### Custom tools + skills from directories\n\n```ts\nimport { createWunderland } from 'wunderland';\nimport type { ITool } from '@framers/agentos';\n\nconst myTool: ITool = {\n id: 'my.tool', name: 'my_tool', displayName: 'My Tool',\n description: 'Does something custom',\n inputSchema: { type: 'object', properties: { query: { type: 'string' } } },\n hasSideEffects: false,\n async execute(args) { return { success: true, output: { result: 'done' } }; },\n};\n\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n tools: { curated: {}, custom: [myTool] },\n skills: {\n names: ['github'],\n dirs: ['./my-custom-skills'], // scan local SKILL.md directories\n includeDefaults: true, // also scan ./skills/, ~/.codex/skills/\n },\n});\n```\n\n### Check what's loaded\n\n```ts\nconst diag = app.diagnostics();\nconsole.log('Tools:', diag.tools.names); // ['web_search', 'giphy_search', ...]\nconsole.log('Skills:', diag.skills.names); // ['github', 'web-search', ...]\nconsole.log('Discovery:', diag.discovery); // { initialized: true, capabilityCount: 25, ... }\n```\n\nSee `docs/LIBRARY_API.md` for the full API reference (approvals, custom tools, diagnostics, advanced modules).\n\n### Discovery recall + dynamic tool exposure\n\n```ts\nconst app = await createWunderland({\n llm: { providerId: 'openai' },\n tools: 'curated',\n discovery: {\n recallProfile: 'aggressive', // default: aggressive | balanced | precision\n },\n});\n\nconst session = app.session();\nawait session.sendText('Investigate recent SQL adapter changes', {\n toolSelectionMode: 'discovered', // default when discovery has results\n // toolSelectionMode: 'all', // optional per-turn override\n});\n```\n\n- `toolSelectionMode` automatically falls back to `all` when discovery has no usable tool hits.\n- Adaptive degraded mode can force `all` tool exposure for recovery.\n- Tool schemas sent to OpenAI-compatible providers are normalized to valid `function.name` values automatically.\n- Optional strict mode: set `toolCalling.strictToolNames=true` (or `WUNDERLAND_STRICT_TOOL_NAMES=true`) to fail fast on rewrites/collisions.\n\n### CLI\n\n```bash\n# Install globally (pnpm recommended — npm on Node 25 has resolution bugs)\npnpm add -g wunderland\n# or: npm install -g wunderland (requires Node 22 LTS)\n\n# Fastest first run\nwunderland quickstart\n\n# Interactive setup wizard\nwunderland setup\n\n# Open the dashboard + guided onboarding tour\nwunderland\n\n# Health check + operator help\nwunderland doctor\nwunderland help getting-started\nwunderland help workflows\nwunderland help tui\n\n# Configure shared provider defaults (image gen, TTS, STT, web search)\nwunderland extensions configure\nwunderland extensions info image-generation\n\n# UI / accessibility\nwunderland --theme cyberpunk\nwunderland --ascii\n\n# Start the agent server\nwunderland start\n\n# Chat with your agent\nwunderland chat\n\n# Health check\nwunderland doctor\n```\n\n### Example files\n\n- `examples/library-chat-basic.mjs` — minimal in-process chat\n- `examples/library-chat-with-tools-and-approvals.mjs` — curated tools + safe approvals\n- `examples/library-chat-image-generation.mjs` — image generation extension with provider defaults\n- `examples/workflow-orchestration.mjs` — deterministic `workflow()` with an LLM-as-judge step\n- `examples/agent-graph-orchestration.mjs` — explicit `AgentGraph` routing with a judge loop\n- `examples/mission-orchestration.mjs` — planner-driven `mission()` plus `explain()` and execution\n- `examples/chat-runtime.mjs` — lower-level runtime helper\n- `examples/workflow-research.yaml` — runnable research-pipeline workflow (search → evaluate → summarize)\n- `examples/mission-deep-research.yaml` — intent-driven deep research mission definition\n- `examples/graph-research-loop.ts` — AgentGraph with conditional retry cycle\n- `examples/graph-judge-pipeline.ts` — LLM-as-judge evaluation pipeline using judgeNode\n- `examples/session-streaming.ts` — streaming session events with `session.stream()`\n- `examples/checkpoint-resume.ts` — checkpoint and resume across session turns\n\nSee `docs/CLI_TUI_GUIDE.md` for the first-run checklist, TUI keybindings, help topics, troubleshooting pointers, and provider-default setup.\n\n---\n\n## Graph-Based Orchestration\n\nWunderland supports three levels of workflow orchestration powered by the AgentOS unified orchestration layer:\n\n### YAML Workflows (Deterministic DAGs)\n\n```yaml\n# research-pipeline.workflow.yaml\nname: research-pipeline\nsteps:\n - id: search\n tool: web_search\n - id: evaluate\n gmi: { instructions: \"Evaluate results\" }\n - id: summarize\n gmi: { instructions: \"Write summary\" }\n```\n\n```bash\n# Execute a workflow YAML file\nwunderland workflows run research-pipeline.workflow.yaml\n\n# Print the compiled node/edge graph\nwunderland workflows explain research-pipeline.workflow.yaml\n```\n\n### YAML Missions (Intent-Driven)\n\n```bash\n# Execute a mission YAML file (writes a per-node report to ./report.md)\nwunderland mission run examples/mission-deep-research.yaml \\\n --input '{\"topic\":\"quantum computing\"}' \\\n --output ./report.md\n\n# Show the planner-derived mission graph\nwunderland mission explain examples/mission-deep-research.yaml\n```\n\n`planner.style` selects the plan template:\n\n| Style | Steps | Best for |\n| ---------- | ------------------------------------------------------ | --------------------------------- |\n| `research` | gather → process → deliver → refine | evidence-backed research (default)|\n| `qa` | research-quick → answer | short factual questions |\n| `creative` | brainstorm → develop → produce → polish | write/design/compose artifacts |\n\nOmit `style` and the goal text auto-classifies: `what is`/`explain`/`how do I` →\n`qa`, `Write a...`/`Compose...`/`Design a...` → `creative`, everything else →\n`research`. The resolved style is shown in the console banner and report header.\n\nBundled examples:\n\n- `examples/mission-deep-research.yaml` — full research pipeline\n- `examples/mission-qa.yaml` — short Q&A\n- `examples/mission-creative.yaml` — write-a-haiku\n\n### Library API\n\n```typescript\nimport { createWunderland } from 'wunderland';\n\nconst app = await createWunderland({ llm: { providerId: 'openai', model: 'gpt-4o' } });\n\n// Load and compile a workflow\nconst flow = await app.loadWorkflow('./research-pipeline.workflow.yaml');\n\n// Stream session events\nconst session = app.session();\nfor await (const event of session.stream('Hello')) {\n if (event.type === 'text_delta') process.stdout.write(event.content);\n}\n\n// Checkpoint and resume\nconst cpId = await session.checkpoint();\nawait session.resume(cpId);\n```\n\n### Prebuilt Templates\n\n| Template | Type | Description |\n|----------|------|-------------|\n| `research-pipeline` | workflow | Search → evaluate → summarize |\n| `content-generation` | workflow | Draft → judge → revise |\n| `data-extraction` | workflow | Fetch → extract → validate |\n| `evaluation` | workflow | Multi-judge scoring |\n| `deep-research` | mission | Planner-driven research |\n| `report-writer` | mission | Structured report generation |\n\nSee `presets/workflows/` and `presets/missions/` for all templates.\n\n---\n\n## What is Wunderland?\n\n**Wunderland** is a free, open-source npm package for deploying autonomous AI agents. It's built on [AgentOS](https://agentos.sh) with security parity tracked against [OpenClaw](https://github.com/openclaw) (see [OPENCLAW_PARITY.md](docs/features/OPENCLAW_PARITY.md)), adding:\n\n- **5-tier security** — prompt-injection defense, dual-LLM auditing, action sandboxing, recursive-error circuit breakers, per-agent cost guards\n- **HEXACO personalities** — six scientifically-grounded personality dimensions (Honesty-Humility, Emotionality, eXtraversion, Agreeableness, Conscientiousness, Openness) that shape agent behavior\n- **PAD mood engine** — real-time Pleasure-Arousal-Dominance emotional states that influence decision-making\n- **37 channel integrations** — Telegram, WhatsApp, Discord, Slack, WebChat, Signal, iMessage, Google Chat, Teams, Matrix, Zalo, Zalo Personal, Email, SMS, IRC, Nostr, Twitch, LINE, Feishu, Mattermost, Nextcloud Talk, Tlon, Twitter / X, Instagram, Reddit, YouTube, Pinterest, TikTok, LinkedIn, Facebook, Threads, Bluesky, Mastodon, Farcaster, Lemmy, Google Business, Blog Publisher\n- **88 curated skills** — pre-built capability packs agents can load on demand\n- **Full CLI** — 28 commands for setup, deployment, management, and debugging\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `wunderland` | Open the interactive TUI dashboard (TTY only) |\n| `wunderland setup` | Interactive setup wizard (LLM provider, channels, personality) |\n| `wunderland help [topic]` | Onboarding guides + keybindings (`wunderland help tui`) |\n| `wunderland start` | Start the agent server (default port 3777) |\n| `wunderland chat` | Chat with your agent in the terminal |\n| `wunderland doctor` | Health check and diagnostics |\n| `wunderland status` | Agent & connection status |\n| `wunderland init