wispy-cli 1.1.0 → 1.1.2

package/README.md

@@ -1,273 +1,571 @@
 # 🌿 Wispy CLI
 
-AI workspace assistant with multi-agent orchestration. Like Claude Code or Codex, but with workstream isolation, budget management, and a team of specialized sub-agents.
+> Your personal AI assistant — chat, automate, and orchestrate from the terminal.
 
-## Quick Start
+[![npm version](https://img.shields.io/npm/v/wispy-cli.svg)](https://www.npmjs.com/package/wispy-cli)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Wispy is a powerful terminal AI assistant that talks to your files, runs commands, orchestrates sub-agents, sends messages to Telegram/Discord/Slack, and remembers things across sessions — all from a single `wispy` command.
+
+## ✨ Features
+
+- 💬 **Interactive REPL + TUI** — chat mode, slash commands, streaming responses
+- 🤖 **7 AI providers** — Gemini, Claude, OpenAI, Groq, DeepSeek, Ollama, OpenRouter
+- 🔧 **18+ built-in tools** — files, shell commands, git, web search, and more
+- 🔌 **MCP server integration** — connect any Model Context Protocol server
+- 📱 **Multi-channel bot** — Telegram, Discord, Slack with session isolation
+- 🧠 **Long-term memory** — persistent facts, daily logs, project notes
+- ⏰ **Cron scheduler** — scheduled tasks with channel delivery
+- 🤝 **Sub-agent orchestration** — spawn parallel agents, steer them, collect results
+- 📂 **Workstream isolation** — separate contexts per project
+
+---
+
+## 🚀 Quick Start
 
 ```bash
+# Install globally
 npm install -g wispy-cli
-export GOOGLE_AI_KEY=your-key   # or ANTHROPIC_API_KEY or OPENAI_API_KEY
+
+# Set your API key (any of these)
+export GOOGLE_AI_KEY=your_key          # Gemini (recommended, has free tier)
+export ANTHROPIC_API_KEY=your_key      # Claude
+export OPENAI_API_KEY=your_key         # OpenAI / GPT
+
+# Start chatting
 wispy
 ```
 
-That's it. No server setup needed — it starts automatically.
+Wispy auto-detects your API key and starts the REPL immediately.
 
-## Features
+---
 
-### Chat & Tools
+## 📦 Installation
+
+### Requirements
+- **Node.js >= 18** (ESM modules required)
+
+### Global install
 ```bash
-wispy                        # Interactive REPL
-wispy "read my package.json" # One-shot with tool use
-wispy --continue "and fix it"# Continue previous session
-wispy --new "fresh start"    # New session
+npm install -g wispy-cli
 ```
 
-Wispy can **read/write files, run commands, search the web** — not just chat.
+### Local install
+```bash
+npm install wispy-cli
+npx wispy
+```
+
+---
+
+## 🗣️ Chat Modes
 
-### Workstream Isolation
+### REPL (default)
 ```bash
-wispy -w backend "fix the API"     # Backend workstream
-wispy -w frontend "add dark mode"  # Frontend workstream  
-wispy overview                      # See all workstreams at a glance
-wispy search "auth"                 # Search across all workstreams
+wispy                    # start interactive chat
+wispy -w myproject       # start in a specific workstream
+wispy --session my-ses   # resume a named session
 ```
 
-Each workstream has its own conversation history, context, and budget.
+**REPL slash commands:**
+```
+/help         — show all slash commands
+/clear        — reset conversation history
+/sessions     — list recent sessions
+/memory       — show memory files
+/tools        — list available tools
+/model        — show current AI model
+/workstream   — show active workstream
+/exit         — exit Wispy
+```
 
-### Multi-Agent Orchestration
+### TUI (Ink-based)
 ```bash
-# AI automatically delegates to specialized sub-agents:
-# 🔍 explorer — codebase search
-# 📋 planner  — strategy design  
-# 🔨 worker   — implementation
-# 🔎 reviewer  — code review & QA
-```
-
-#### Execution Modes
-- **Pipeline** — Sequential chaining: `explore → plan → implement → review`
-- **Ralph mode** — Persistence: retry until reviewer confirms done (max 5 rounds)
-- **Async agents** — Fire-and-forget background tasks
-
-### 7 Providers (Auto-detected)
-
-| Provider | Env Variable | Free Tier |
-|----------|-------------|-----------|
-| Google AI (Gemini) | `GOOGLE_AI_KEY` | ✅ |
-| Anthropic (Claude) | `ANTHROPIC_API_KEY` | ❌ |
-| OpenAI (GPT-4o) | `OPENAI_API_KEY` | ❌ |
-| OpenRouter | `OPENROUTER_API_KEY` | Some |
-| Groq | `GROQ_API_KEY` | ✅ |
-| DeepSeek | `DEEPSEEK_API_KEY` | ✅ |
-| Ollama (local) | `OLLAMA_HOST` | ✅ |
-
-Also auto-detects macOS Keychain credentials.
-
-### Cost Optimization
-- **Smart model routing** — simple tasks → cheap model, complex → mid, critical → expensive
-- **Per-workstream budgets** — `/budget set 5.00` to cap spending
-- **Context window optimization** — auto-trims old messages to save tokens
-- **Token tracking** — see cost after every response
-
-### Security
-- Sandboxed command execution (macOS Seatbelt)
-- Process hardening (core dump disable, ptrace block)
-- Audit logging (JSON Lines)
-- Rate limiting + CORS restriction
-- API key isolation per workstream
-
-## In-Session Commands
-
-| Command | Description |
-|---------|-------------|
-| `/help` | Show all commands |
-| `/compact` | Compress conversation history |
-| `/memory <type> <text>` | Save to persistent memory |
-| `/budget` | Show spending per workstream |
-| `/budget set <usd>` | Set budget limit |
-| `/overview` | Director view — all workstreams |
-| `/search <keyword>` | Search across workstreams |
-| `/cost` | Show session token usage |
-| `/workstreams` | List all workstreams |
-| `/provider` | Show current provider |
-| `/model [name]` | Show/change model |
-| `/clear` | Reset conversation |
-| `/quit` | Exit |
-
-## Project Context (WISPY.md)
-
-Create a `WISPY.md` in your project root or `~/.wispy/WISPY.md`. It gets loaded into every conversation turn (up to 40K chars), just like Claude Code's `CLAUDE.md`.
-
-```markdown
-# WISPY.md
-## About this project
-- Next.js 15 app with TypeScript
-- Use Tailwind CSS
-- Korean comments preferred
-```
-
-## Workstream Context (work.md)
-
-Each workstream can have its own `work.md` — loaded every turn, like WISPY.md but scoped to that workstream.
+wispy-tui                # full terminal UI with scrollable history
+wispy-tui -w myproject   # workstream-specific TUI
+```
 
+### One-shot (non-interactive)
 ```bash
-/work init                    # Create work.md for current workstream
-/work set "deadline: Friday"  # Append context
-/work                         # View current work.md
+wispy ask "What files are in the current directory?"
+wispy exec "summarize README.md"
 ```
 
-File locations (searched in order):
-1. `~/.wispy/conversations/<workstream>.work.md`
-2. `.wispy/<workstream>.work.md`
-3. `work.md` (project root fallback)
+### Overview
+```bash
+wispy overview           # show all workstreams and recent activity
+```
 
-```markdown
-# backend
-## Goals
-- Migrate to PostgreSQL
-- Add rate limiting
+---
 
-## Context
-- Using Express.js + TypeORM
-- Staging server: staging.example.com
-```
+## 🤖 AI Providers
 
-## Persistent Memory
+Wispy detects your configured provider automatically. Priority order:
 
-Wispy remembers across sessions via `~/.wispy/memory/`:
+| Provider | Env Var | Default Model |
+|----------|---------|---------------|
+| **Google AI** (Gemini) | `GOOGLE_AI_KEY` or `GEMINI_API_KEY` | `gemini-2.5-flash` |
+| **Anthropic** (Claude) | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| **OpenAI** | `OPENAI_API_KEY` | `gpt-4o` |
+| **OpenRouter** | `OPENROUTER_API_KEY` | `anthropic/claude-sonnet-4` |
+| **Groq** | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
+| **DeepSeek** | `DEEPSEEK_API_KEY` | `deepseek-chat` |
+| **Ollama** (local) | `OLLAMA_HOST` | `llama3.2` |
 
+### Override provider
 ```bash
-/memory user "prefers dark mode"
-/memory project "deadline is Friday"
-/memory feedback "don't use var, use const"
-/memory references "API docs: https://..."
+WISPY_PROVIDER=anthropic wispy
+WISPY_MODEL=claude-3-5-haiku wispy
 ```
 
-## Multi-Channel Bot Support (v0.6.0)
+### Config file
+```json
+// ~/.wispy/config.json
+{
+  "provider": "google",
+  "model": "gemini-2.5-flash",
+  "apiKey": "optional-if-not-in-env"
+}
+```
+
+---
+
+## 🔧 Built-in Tools
+
+Wispy gives the AI access to these tools automatically:
 
-Run Wispy as a bot on Telegram, Discord, and Slack — all at once or individually.
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read any file's contents |
+| `write_file` | Write or create files |
+| `file_edit` | Edit files with find-and-replace |
+| `file_search` | Search files with regex (like grep) |
+| `list_directory` | List directory contents |
+| `run_command` | Execute shell commands |
+| `git_status` / `git_diff` / `git_log` | Git operations |
+| `web_search` | Search the web |
+| `memory_save` | Save facts to persistent memory |
+| `memory_get` | Retrieve a memory by key |
+| `memory_search` | Full-text search across all memories |
+| `memory_list` | List all memory files |
+| `memory_append` | Append to a memory file |
+| `memory_delete` | Delete a memory file |
+| `spawn_subagent` | Launch a parallel sub-agent |
+| `list_subagents` | List running sub-agents |
+| `get_subagent_result` | Get a sub-agent's result |
+| `kill_subagent` | Cancel a sub-agent |
 
-### Quick Start
+---
 
+## 📱 Channel Setup
+
+Run Wispy as a multi-platform bot that responds to messages in Telegram, Discord, or Slack.
+
+### Start the bot server
 ```bash
-# Set up a channel (interactive)
-wispy channel setup telegram
-wispy channel setup discord
-wispy channel setup slack
+wispy channels start              # start all configured channels
+wispy channels start --telegram   # start only Telegram
+```
+
+### Telegram
+1. Create a bot via [@BotFather](https://t.me/BotFather)
+2. Copy the bot token
+3. Configure:
+```bash
+# Option 1: env var
+export WISPY_TELEGRAM_TOKEN=your_bot_token
+
+# Option 2: config file
+# ~/.wispy/channels.json
+{
+  "telegram": {
+    "enabled": true,
+    "token": "your_bot_token"
+  }
+}
+```
+
+### Discord
+1. Create a bot at [discord.com/developers](https://discord.com/developers/applications)
+2. Install peer dependency: `npm install -g discord.js`
+3. Configure:
+```json
+{
+  "discord": {
+    "enabled": true,
+    "token": "your_discord_token",
+    "clientId": "your_client_id",
+    "guildId": "optional_guild_id"
+  }
+}
+```
+
+### Slack
+1. Create a Slack app at [api.slack.com](https://api.slack.com/apps)
+2. Install peer dependency: `npm install -g @slack/bolt`
+3. Configure:
+```json
+{
+  "slack": {
+    "enabled": true,
+    "botToken": "xoxb-your-token",
+    "appToken": "xapp-your-token",
+    "signingSecret": "your-signing-secret"
+  }
+}
+```
+
+Each chat/user gets an isolated session — Wispy remembers context per conversation.
 
-# Start all configured channels
-wispy --serve
+---
 
-# Or start a single channel
-wispy --telegram
-wispy --discord
-wispy --slack
+## 🧠 Memory System
 
-# List configured channels
-wispy channel list
+Wispy has a file-based long-term memory stored in `~/.wispy/memory/`.
 
-# Test a channel connection
-wispy channel test telegram
+### Using memory in chat
+Just ask Wispy to remember things:
+```
+You: Remember that my project uses TypeScript and Next.js 15
+Wispy: Got it! I'll remember that. 🌿
 ```
 
-### Telegram Setup
+Or use memory tools explicitly:
+```
+You: Save this to memory: the deployment command is `vercel --prod`
+```
 
-1. Talk to [@BotFather](https://t.me/BotFather) on Telegram
-2. Send `/newbot`, follow prompts, copy the token
-3. Run `wispy channel setup telegram`
+### Memory structure
+```
+~/.wispy/memory/
+├── MEMORY.md           — main persistent memory (auto-included in every chat)
+├── user.md             — user preferences
+├── daily/
+│   └── 2026-04-03.md  — daily logs
+└── projects/
+    └── myapp.md        — project-specific notes
+```
 
-**Or** set the env var:
+### Memory CLI
 ```bash
-export WISPY_TELEGRAM_TOKEN=your-token
-wispy --telegram
+wispy memory list                    # list all memory files
+wispy memory get MEMORY              # show main memory
+wispy memory save user "I prefer TypeScript"
+wispy memory search "deployment"     # full-text search
+wispy memory delete daily/old-date
 ```
 
-Bot commands: `/start`, `/clear`, `/model`, `/help`
+---
+
+## ⏰ Cron Scheduler
 
-### Discord Setup
+Schedule tasks to run automatically and optionally deliver results to a channel.
 
-1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
-2. Create an app → Bot → copy the token
-3. Enable **Message Content Intent** in Bot settings
-4. Invite bot to your server with `bot` + `applications.commands` scopes
-5. Run `wispy channel setup discord`
+### Add a scheduled job
+```bash
+# Every morning briefing
+wispy cron add \
+  --name "Morning Briefing" \
+  --schedule "0 9 * * *" \
+  --task "Summarize my pending tasks and give me a morning overview" \
+  --channel "telegram:YOUR_CHAT_ID"
+
+# Every 30 minutes
+wispy cron add \
+  --name "Price Check" \
+  --schedule every:1800000 \
+  --task "Check the current price of BTC and ETH"
+
+# One-shot at specific time
+wispy cron add \
+  --name "Reminder" \
+  --schedule "at:2026-12-31T09:00:00Z" \
+  --task "Remind me it's New Year's Eve!"
+```
 
-**Or** set the env var:
+### Schedule formats
+| Format | Example | Description |
+|--------|---------|-------------|
+| Cron expression | `0 9 * * *` | Standard 5-field cron (daily at 9am) |
+| Interval | `every:1800000` | Every N milliseconds (30 min) |
+| One-shot | `at:2026-12-31T09:00:00Z` | Specific ISO timestamp |
+
+### Manage jobs
 ```bash
-export WISPY_DISCORD_TOKEN=your-token
-wispy --discord
+wispy cron list           # list all jobs
+wispy cron run <id>       # run a job immediately
+wispy cron remove <id>    # delete a job
+wispy cron history <id>   # view execution history
+```
+
+### Start the scheduler
+```bash
+wispy cron start          # start the cron scheduler daemon
+```
+
+---
+
+## 🤝 Sub-agents
+
+Delegate complex tasks to parallel sub-agents and collect results.
+
+### From chat
+```
+You: Spawn a sub-agent to analyze all TypeScript files in src/ and report issues
+Wispy: Spawning sub-agent 'code-review'... 🌿
 ```
 
-Triggers: mention @Wispy, `!clear`, `!model`, `!help`, or DM the bot.
+### Sub-agent tools (available to Wispy in chat)
+- `spawn_subagent` — start a sub-agent with a task
+- `list_subagents` — see all active/recent sub-agents
+- `get_subagent_result` — wait for and retrieve results
+- `kill_subagent` — cancel a running sub-agent
+- `steer_subagent` — send mid-task guidance
 
-### Slack Setup
+### Sub-agent lifecycle
+```
+pending → running → completed
+                 ↘ failed
+                 ↘ killed
+                 ↘ timeout
+```
 
-1. Go to [Slack API](https://api.slack.com/apps) → Create New App → From scratch
-2. Enable **Socket Mode** → copy App-Level Token (`xapp-...`)
-3. OAuth & Permissions → copy Bot User OAuth Token (`xoxb-...`)
-4. Subscribe to `app_mention` + `message.im` events
-5. Add `/wispy` slash command
-6. Run `wispy channel setup slack`
+Sub-agent results persist to `~/.wispy/subagents/` for later retrieval.
 
-**Or** set env vars:
+---
+
+## 🔌 MCP Integration
+
+Connect any [Model Context Protocol](https://modelcontextprotocol.io) server and Wispy will automatically use its tools.
+
+### Configuration
+```json
+// ~/.wispy/mcp.json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "your_token" }
+    }
+  }
+}
+```
+
+### MCP CLI
 ```bash
-export WISPY_SLACK_BOT_TOKEN=xoxb-...
-export WISPY_SLACK_APP_TOKEN=xapp-...
-wispy --slack
+wispy mcp list         # list configured servers
+wispy mcp status       # show connected servers and their tools
+wispy mcp add          # interactive server setup
 ```
 
-Triggers: `@mention`, DMs, `/wispy <message>` slash command.
+---
+
+## ⚙️ Configuration
+
+All configuration lives in `~/.wispy/`:
 
-### channels.json Config
+```
+~/.wispy/
+├── config.json         — main config (provider, model, apiKey)
+├── channels.json       — channel bot configuration
+├── mcp.json            — MCP server configuration
+├── sessions/           — conversation history
+├── memory/             — long-term memory files
+├── cron/               — scheduler jobs and history
+├── subagents/          — sub-agent results
+└── audit/              — audit log (JSONL per day)
+```
 
-Stored at `~/.wispy/channels.json`:
+### config.json reference
 ```json
 {
-  "telegram": { "enabled": true, "token": "..." },
-  "discord":  { "enabled": true, "token": "..." },
-  "slack":    { "enabled": true, "botToken": "...", "appToken": "..." }
+  "provider": "google",           // auto-detected if omitted
+  "model": "gemini-2.5-flash",   // defaults to provider's default
+  "apiKey": "...",                // env var takes precedence
+  "workstream": "default"         // default workstream
 }
 ```
 
-### Optional Dependencies
+### Environment variables
+```bash
+WISPY_PROVIDER=google           # force provider
+WISPY_MODEL=gemini-2.5-flash    # force model
+WISPY_WORKSTREAM=myproject      # set active workstream
+WISPY_DEBUG=1                   # enable debug output
+```
+
+---
 
-Channel adapters use peer dependencies — install only what you need:
+## 📂 Workstream Isolation
+
+Workstreams let you maintain separate AI contexts for different projects.
 
 ```bash
-npm install grammy          # Telegram
-npm install discord.js      # Discord
-npm install @slack/bolt     # Slack
+wispy -w frontend       # chat in "frontend" workstream
+wispy -w backend        # completely separate context
+wispy overview          # see all workstreams
 ```
 
-Each adapter gracefully fails with a helpful install message if the package isn't present.
+Each workstream has its own:
+- Conversation sessions
+- Context/memory scope
+- Sub-agent history
+
+---
+
+## 🏗️ Architecture
+
+```
+                         ┌─────────────────────────────┐
+                         │         WispyEngine          │
+                         │   core/engine.mjs            │
+                         │   processMessage() ─────────┐│
+                         └─────────────────────────────┘│
+                                     │                  │
+          ┌──────────────────────────┼──────────┐       │
+          │              │           │          │       │
+    REPL          TUI          channels    server.mjs   │
+ (bin/wispy)  (bin/wispy-tui) (lib/channels/)          │
+                                                        │
+                              ┌─────────────────────────┘
+                              │
+          ┌───────────────────┼──────────────────────────┐
+          │                   │                          │
+   ProviderRegistry    ToolRegistry              SessionManager
+   core/providers.mjs  core/tools.mjs            core/session.mjs
+   (Gemini/Claude/     (18+ built-in +            (file-based,
+    OpenAI/Groq/        MCP tools)                per-channel)
+    DeepSeek/Ollama/
+    OpenRouter)
+          │
+          └── MemoryManager     CronManager     SubAgentManager
+              core/memory.mjs   core/cron.mjs   core/subagents.mjs
+              (~/.wispy/        (~/.wispy/       (~/.wispy/
+               memory/)          cron/)           subagents/)
+```
+
+All surfaces (REPL, TUI, channels) call `WispyEngine.processMessage()` — one core, many interfaces.
+
+---
+
+## 🛠️ Development
+
+```bash
+# Clone
+git clone https://github.com/mindsurf0176-ui/poropo-workspace
+cd wispy-cli
 
-### Per-Chat Session Isolation
+# Install
+npm install
 
-Each chat/channel/DM gets its own conversation history stored in:
-`~/.wispy/channel-sessions/<channel>/<chatId>.json`
+# Run tests (91 integration tests)
+npm test
 
-No cross-contamination between users or channels.
+# Development REPL
+node bin/wispy.mjs
+```
 
-## Architecture
+### Running tests
+```bash
+npm test                    # run all integration tests
+npm run test:verbose        # run with spec reporter
+npm run test:basic          # run basic smoke tests only
+```
 
+### Project structure
+```
+wispy-cli/
+├── bin/
+│   ├── wispy.mjs           — main CLI entry point
+│   └── wispy-tui.mjs       — TUI entry point (Ink)
+├── core/
+│   ├── engine.mjs          — WispyEngine (main chat loop)
+│   ├── session.mjs         — SessionManager
+│   ├── providers.mjs       — ProviderRegistry (7 AI providers)
+│   ├── tools.mjs           — ToolRegistry (18+ built-in tools)
+│   ├── memory.mjs          — MemoryManager
+│   ├── cron.mjs            — CronManager (scheduler)
+│   ├── subagents.mjs       — SubAgentManager
+│   ├── mcp.mjs             — MCP client/manager
+│   ├── config.mjs          — config loader + provider detection
+│   └── index.mjs           — public API exports
+├── lib/
+│   ├── wispy-repl.mjs      — REPL implementation
+│   ├── wispy-tui.mjs       — TUI implementation (Ink/React)
+│   └── channels/
+│       ├── index.mjs       — ChannelManager
+│       ├── telegram.mjs    — Telegram adapter (grammY)
+│       ├── discord.mjs     — Discord adapter (discord.js)
+│       ├── slack.mjs       — Slack adapter (@slack/bolt)
+│       └── base.mjs        — ChannelAdapter base class
+└── tests/
+    ├── core-engine.test.mjs
+    ├── core-session.test.mjs
+    ├── core-memory.test.mjs
+    ├── core-cron.test.mjs
+    ├── core-subagents.test.mjs
+    ├── core-tools.test.mjs
+    └── channels.test.mjs
 ```
-wispy (CLI REPL / TUI)
-  ↕ Gemini/Claude/OpenAI API (tool calling)
-  ↕ AWOS Server (auto-started, sandboxed tools)
-  ↕ Local Node (macOS file/browser/app actions)
 
-wispy --serve (Channel Bot Mode)
-  ↕ Telegram (grammY long polling)
-  ↕ Discord (discord.js gateway)
-  ↕ Slack (bolt socket mode)
-  ↕ Gemini/Claude/OpenAI API (per-chat sessions)
+---
+
+## 📋 CLI Reference
+
+```
+Usage: wispy [options] [command]
+
+Commands:
+  wispy                    — start interactive REPL
+  wispy ask <message>      — one-shot chat
+  wispy exec <message>     — one-shot execution
+  wispy overview           — show workstream overview
+  wispy sessions           — list recent sessions
+  wispy memory <cmd>       — manage long-term memory
+  wispy cron <cmd>         — manage scheduled jobs
+  wispy channels <cmd>     — manage channel bots
+  wispy mcp <cmd>          — manage MCP servers
+  wispy server <cmd>       — start/stop HTTP/WS server
+  wispy audit <cmd>        — view audit log
+
+Options:
+  -w, --workstream <name>   — set active workstream
+  --session <id>            — resume a specific session
+  --model <name>            — override AI model
+  --provider <name>         — override AI provider
+  --help                    — show help
+  --version                 — show version
 ```
 
-## Requirements
+---
+
+## 🔑 API Keys
+
+Get free/paid API keys from:
+- **Google AI (Gemini)** — [aistudio.google.com/apikey](https://aistudio.google.com/apikey) *(free tier available)*
+- **Anthropic (Claude)** — [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
+- **OpenAI** — [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+- **OpenRouter** — [openrouter.ai/keys](https://openrouter.ai/keys) *(free credits)*
+- **Groq** — [console.groq.com/keys](https://console.groq.com/keys) *(free tier)*
+- **DeepSeek** — [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)
+- **Ollama** — [ollama.ai](https://ollama.ai) *(fully local, no key needed)*
+
+---
+
+## 📝 License
+
+MIT — see [LICENSE](LICENSE)
+
+---
 
-- Node.js 20+
-- One API key (Google AI recommended for free tier)
-- macOS or Linux
+## 🙌 Credits
 
-## License
+Built by Minseo & Poropo 🫧
 
-Apache-2.0 — Minseo & Poropo 🌿
+*Wispy is a small ghost that lives in terminals — floating between code, files, and servers.*

package/core/cron.mjs

@@ -119,6 +119,8 @@ export class CronManager {
     this._running = true;
     this._tick();
     this._timer = setInterval(() => this._tick(), TICK_INTERVAL_MS);
+    // unref() so the timer doesn't prevent the process from exiting
+    if (this._timer?.unref) this._timer.unref();
     console.error(`[wispy-cron] Scheduler started (checking every ${TICK_INTERVAL_MS / 1000}s)`);
   }
 

package/core/engine.mjs

@@ -1009,6 +1009,9 @@ export class WispyEngine {
 
   destroy() {
     try { this.mcpManager.disconnectAll(); } catch {}
+    try { this.sessions.destroyAll?.(); } catch {}
+    try { this.subagents.killAll?.(); } catch {}
+    try { this.audit.close?.(); } catch {}
   }
 }
 

package/core/providers.mjs

@@ -345,7 +345,7 @@ export class ProviderRegistry {
     if (this._provider === "openrouter") headers["HTTP-Referer"] = "https://wispy.dev";
 
     const supportsTools = !["ollama"].includes(this._provider);
-    const body = { model, messages: openaiMessages, temperature: 0.7, max_tokens: 4096 };
+    const body = { model, messages: openaiMessages, temperature: 0.7, max_tokens: 4096, stream: true };
     if (supportsTools && tools.length > 0) {
       body.tools = tools.map(t => ({
         type: "function",
@@ -364,24 +364,65 @@ export class ProviderRegistry {
       throw new Error(`OpenAI API error ${response.status}: ${err.slice(0, 300)}`);
     }
 
-    const data = await response.json();
-    const choice = data.choices?.[0];
-    if (!choice) throw new Error("No response from OpenAI");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let fullText = "";
+    const toolCallsMap = {};
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const data = line.slice(6).trim();
+        if (!data || data === "[DONE]") continue;
+
+        try {
+          const event = JSON.parse(data);
+          const delta = event.choices?.[0]?.delta;
+          if (!delta) continue;
+
+          // Text content
+          if (delta.content) {
+            fullText += delta.content;
+            opts.onChunk?.(delta.content);
+          }
+
+          // Tool calls (streamed as incremental chunks)
+          if (delta.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              const idx = tc.index ?? 0;
+              if (!toolCallsMap[idx]) {
+                toolCallsMap[idx] = { id: tc.id ?? `call_${idx}`, name: "", arguments: "" };
+              }
+              if (tc.id) toolCallsMap[idx].id = tc.id;
+              if (tc.function?.name) toolCallsMap[idx].name += tc.function.name;
+              if (tc.function?.arguments) toolCallsMap[idx].arguments += tc.function.arguments;
+            }
+          }
+        } catch { /* skip malformed chunks */ }
+      }
+    }
 
-    if (choice.message?.tool_calls?.length > 0) {
-      const calls = choice.message.tool_calls.map(tc => ({
+    const toolCalls = Object.values(toolCallsMap);
+    if (toolCalls.length > 0) {
+      const calls = toolCalls.map(tc => ({
         id: tc.id,
-        name: tc.function.name,
-        args: JSON.parse(tc.function.arguments),
+        name: tc.name,
+        args: (() => { try { return JSON.parse(tc.arguments); } catch { return {}; } })(),
       }));
       this._sessionTokens.output += this._estimateTokens(JSON.stringify(calls));
       return { type: "tool_calls", calls };
     }
 
-    const text = choice.message?.content ?? "";
-    this._sessionTokens.output += this._estimateTokens(text);
-    opts.onChunk?.(text);
-    return { type: "text", text };
+    this._sessionTokens.output += this._estimateTokens(fullText);
+    return { type: "text", text: fullText };
   }
 
   formatCost() {

package/core/tools.mjs

@@ -337,10 +337,18 @@ export class ToolRegistry {
     try {
       const serverUrl = `http://127.0.0.1:${DEFAULT_SERVER_PORT}`;
       if (name === "read_file") {
+        // Resolve path relative to process.cwd() before sending to server
+        let resolvedPath = args.path.replace(/^~/, os.homedir());
+        if (!path.isAbsolute(resolvedPath)) {
+          resolvedPath = path.resolve(process.cwd(), resolvedPath);
+        }
+        if (process.env.WISPY_DEBUG) {
+          process.stderr.write(`[wispy] read_file via server: "${args.path}" → "${resolvedPath}"\n`);
+        }
         const resp = await fetch(`${serverUrl}/api/node-filesystem-actions`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ subAction: "read_file", path: args.path }),
+          body: JSON.stringify({ subAction: "read_file", path: resolvedPath }),
           signal: AbortSignal.timeout(10_000),
         });
         const data = await resp.json();
@@ -386,7 +394,13 @@ export class ToolRegistry {
     try {
       switch (name) {
         case "read_file": {
-          const filePath = args.path.replace(/^~/, os.homedir());
+          let filePath = args.path.replace(/^~/, os.homedir());
+          if (!path.isAbsolute(filePath)) {
+            filePath = path.resolve(process.cwd(), filePath);
+          }
+          if (process.env.WISPY_DEBUG) {
+            process.stderr.write(`[wispy] read_file: "${args.path}" → "${filePath}"\n`);
+          }
           const content = await readFile(filePath, "utf8");
           const truncated = content.length > 10_000
             ? content.slice(0, 10_000) + `\n\n... (truncated, ${content.length} chars total)`
@@ -395,7 +409,10 @@ export class ToolRegistry {
         }
 
         case "write_file": {
-          const filePath = args.path.replace(/^~/, os.homedir());
+          let filePath = args.path.replace(/^~/, os.homedir());
+          if (!path.isAbsolute(filePath)) {
+            filePath = path.resolve(process.cwd(), filePath);
+          }
           const dir = path.dirname(filePath);
           await mkdir(dir, { recursive: true });
           await writeFile(filePath, args.content, "utf8");
@@ -453,7 +470,10 @@ export class ToolRegistry {
         }
 
         case "file_edit": {
-          const filePath = args.path.replace(/^~/, os.homedir());
+          let filePath = args.path.replace(/^~/, os.homedir());
+          if (!path.isAbsolute(filePath)) {
+            filePath = path.resolve(process.cwd(), filePath);
+          }
           const content = await readFile(filePath, "utf8");
           if (!content.includes(args.old_text)) {
             return { success: false, error: `Text not found in ${filePath}` };

package/lib/wispy-repl.mjs

@@ -865,8 +865,11 @@ async function runOneShot(engine, message) {
     } else {
       console.error(red(`\n❌ ${err.message.slice(0, 200)}`));
     }
+    engine.destroy();
     process.exit(1);
   }
+  engine.destroy();
+  process.exit(0);
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "wispy-cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "🌿 Wispy — AI workspace assistant with multi-agent orchestration and multi-channel bot support",
-  "license": "Apache-2.0",
+  "license": "MIT",
   "author": "Minseo & Poropo",
+  "homepage": "https://github.com/mindsurf0176-ui/poropo-workspace/tree/master/agent-workstream-os/wispy-cli#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mindsurf0176-ui/poropo-workspace"
+    "url": "git+https://github.com/mindsurf0176-ui/poropo-workspace.git",
+    "directory": "agent-workstream-os/wispy-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/mindsurf0176-ui/poropo-workspace/issues"
   },
   "keywords": [
     "ai",
@@ -19,13 +24,25 @@
     "gemini",
     "claude",
     "openai",
+    "groq",
+    "deepseek",
+    "ollama",
+    "openrouter",
     "tui",
     "ink",
     "telegram",
     "discord",
     "slack",
     "bot",
-    "chatbot"
+    "chatbot",
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "cron",
+    "scheduler",
+    "subagent",
+    "terminal",
+    "repl"
   ],
   "type": "module",
   "bin": {
@@ -41,7 +58,9 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "node --test test/basic.test.mjs"
+    "test": "node --test --test-force-exit --test-timeout=15000 tests/*.test.mjs",
+    "test:basic": "node --test --test-force-exit test/basic.test.mjs",
+    "test:verbose": "node --test --test-force-exit --test-timeout=15000 --test-reporter=spec tests/*.test.mjs"
   },
   "dependencies": {
     "cron-parser": "^5.5.0",
@@ -68,6 +87,6 @@
     }
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=18.0.0"
   }
 }