ohwow 0.1.9 → 0.1.10

package/README.md

@@ -1,6 +1,8 @@
 # ohwow
 
-A local AI agent runtime. Free to use with [Ollama](https://ollama.com) for local models. Enterprise features (cloud dashboard sync, WhatsApp, Telegram, scheduling, proactive engine) unlock with an [ohwow.fun](https://ohwow.fun) subscription.
+Send me a message for support at ogsus@ohwow.fun
+
+A local AI agent runtime. Free to use with [Ollama](https://ollama.com) for local models. Enterprise features (cloud dashboard sync, WhatsApp, Telegram, scheduling, proactive engine, automations, voice) unlock with an [ohwow.fun](https://ohwow.fun) subscription.
 
 ## Getting Started
 
@@ -24,28 +26,63 @@ npm install ohwow -g
 ohwow
 ```
 
-On first launch, a setup wizard appears in your terminal. For the free tier, just point it at your Ollama instance. For enterprise features, enter your license key (from the ohwow.fun dashboard, under Settings > License) and your Anthropic API key. These are saved locally so you only do this once.
+## First Launch
+
+A setup wizard appears in your terminal. For the free tier, just point it at your Ollama instance. For enterprise features, enter your license key (from the ohwow.fun dashboard, under Settings > License) and your Anthropic API key.
 
-After setup, the runtime opens into a TUI (terminal UI) with tabs for your dashboard, agents, tasks, approvals, activity, schedules, plans, and a chat interface. Use arrow keys or tab to navigate. Everything you see in the web dashboard is also here, running locally.
+Config is saved to `~/.ohwow/config.json`. You only do this once.
 
-### What Happens at Startup
+## What Happens at Startup
 
 Once configured, the runtime:
 
-1. Initializes a local database
-2. Connects to ohwow.fun and syncs your agent configurations
-3. Starts the orchestrator, scheduler, and proactive engine
-4. Connects messaging channels (WhatsApp, Telegram) if you've set them up
-5. Launches a local web UI
-6. Begins polling for tasks dispatched from the dashboard
+1. Loads config from `~/.ohwow/config.json`
+2. Spawns the daemon process
+3. Initializes the local SQLite database
+4. Starts the execution engine, orchestrator, and model router
+5. Connects messaging channels (WhatsApp, Telegram) if configured
+6. Starts the scheduler, proactive engine, and trigger evaluator
+7. Launches the HTTP server (default port 7700)
+8. Connects to the ohwow.fun control plane (enterprise)
+9. Opens a WebSocket for real-time updates
+
+From here, agents execute tasks on your hardware using your own API keys. The dashboard sends the work, your machine does the thinking.
+
+## CLI Commands
+
+| Command | What it does |
+|---|---|
+| `ohwow` | Start the TUI (default) |
+| `ohwow --daemon` | Start daemon in foreground (for systemd/launchd/Docker) |
+| `ohwow stop` | Stop the daemon |
+| `ohwow status` | Check daemon status (PID and port) |
+| `ohwow logs` | Tail daemon logs |
+| `ohwow restart` | Restart the daemon |
+
+## TUI
+
+The terminal UI opens into a chat interface with tab navigation. Use arrow keys or tab to switch between:
 
-From here, agents execute tasks on your hardware using your own API key. The dashboard sends the work, your machine does the thinking.
+- **Dashboard** — overview of your workspace
+- **Agents** — manage agent configs, memory, and capabilities
+- **Tasks** — view and manage running/completed tasks
+- **Approvals** — review pending items before execution (enterprise)
+- **Activity** — live feed of everything happening
+- **Automations** — webhook-based automation triggers (enterprise)
+- **Contacts** — CRM with leads, customers, partners
+- **Settings** — config, connections, license
 
-## Using the Orchestrator
+Everything you see in the web dashboard is also here, running locally.
 
-The orchestrator is a conversational assistant built into the runtime with 40+ tools. Open the Chat tab in the TUI, or use the web UI from your browser.
+## Web UI
+
+The runtime serves a built-in React app at `http://localhost:7700`. Same capabilities as the TUI. Useful if you prefer a graphical interface or want to share access with your team on the local network. Override the port with the `OHWOW_PORT` env var.
+
+## Orchestrator
+
+The orchestrator is a conversational assistant built into the runtime with 40+ tools. Open the Chat tab in the TUI, or use the web UI.
 
-You can talk to it naturally. Some examples of what it can do:
+You can talk to it naturally:
 
 | What you say | What happens |
 |---|---|
@@ -64,7 +101,7 @@ The orchestrator covers: agents, tasks, projects, CRM (contacts, pipeline, event
 
 ### Agent Memory
 
-After each task, key facts, skills, and feedback are extracted and stored locally. These memories are compiled into the agent's context on future tasks. Agents improve the more they work. You can view any agent's memory from the Agents tab.
+After each task, key facts, skills, and feedback are extracted and stored locally. Memories are periodically consolidated to keep context sharp. On future tasks, relevant memories are retrieved via RAG and compiled into the agent's context. Agents improve the more they work. View any agent's memory from the Agents tab.
 
 ### Browser Automation
 
@@ -74,42 +111,68 @@ Agents can browse the web using Playwright. Navigation, clicking, form filling,
 
 Connect WhatsApp through a QR code scan in Settings (no Meta business API needed). Connect Telegram with a bot token. Once connected, incoming messages route to the orchestrator automatically. Your agents can reply, take action, or flag things for your attention. You control which chats are allowed.
 
-### Agent-to-Agent (A2A)
+### Voice
 
-Connect to external agents using the A2A protocol. Each agent publishes a card describing its capabilities. You set trust levels to control what external agents can do. Managed from the A2A tab or through the orchestrator.
+Full voice pipeline with local and cloud options:
 
-### Scheduling
+- **Speech-to-Text**: Voicebox (Whisper via local FastAPI server), WhisperLocal (via Ollama), or WhisperAPI (OpenAI cloud fallback)
+- **Text-to-Speech**: VoiceboxTTS (local), Piper (local), or OpenAI TTS (cloud fallback)
 
-Set agents or workflows to run on cron schedules. Create schedules through conversation ("schedule the analyst every Monday at 8am") or from the Schedules tab. Toggle them on and off as needed.
+### A2A Protocol
 
-### Goal Planning
+Connect to external agents using the [A2A protocol](https://google.github.io/A2A/) over JSON-RPC 2.0. Each agent publishes a card at `/.well-known/agent-card.json` describing its capabilities. Trust levels (`read_only`, `execute`, `autonomous`, `admin`) control what external agents can do. Scopes cover tasks, agents, results, and file access. Managed from the A2A tab or through the orchestrator.
 
-For complex goals, the orchestrator can break them into multi-step plans with agent assignments and dependencies. Plans start as drafts. You review the steps, approve or reject, and track execution from the Plans tab.
+### Scheduling and Proactive Engine
 
-### Approval Workflows
+Set agents or workflows to run on cron schedules. Create schedules through conversation ("schedule the analyst every Monday at 8am") or from the Schedules tab.
 
-Some tasks pause for your sign-off before executing. The Approvals tab shows pending items. Approve to proceed, or reject with feedback. Rejected tasks can retry with your notes included.
+The proactive engine runs every 30 minutes and checks for overdue tasks, aging approvals, and idle agents. It generates nudges (suggestions, not auto-executions) so nothing falls through the cracks.
+
+### Goal Planning and Approvals
+
+For complex goals, the orchestrator breaks them into multi-step plans with agent assignments and dependencies. Plans start as drafts. You review the steps, approve or reject, and track execution from the Plans tab. Rejected tasks can retry with your feedback included.
 
 ### Projects and CRM
 
 Organize tasks into projects with Kanban boards (backlog, todo, in progress, review, done). The built-in CRM tracks contacts (leads, customers, partners), logs events (calls, emails, meetings), and gives you pipeline analytics. All stored locally.
 
-### Local Models with Ollama
+### Automations and Triggers
+
+Webhook-based automations that fire on external events. Configure field mapping to extract data from incoming payloads and route it to agents or workflows. Managed from the Automations tab (enterprise).
 
-If you run [Ollama](https://ollama.com) locally, the runtime can route lightweight tasks to your local model instead of Claude. Complex work still goes to Claude. If Ollama goes down, everything falls back automatically.
+### Workflows
+
+DAG-based multi-agent execution graphs. Define sequences of agent tasks with conditions and branches. Workflows can be triggered manually, on a schedule, or via automation triggers.
+
+### MCP Servers
+
+Integrate external tools via the [Model Context Protocol](https://modelcontextprotocol.io/). Supports stdio (subprocess) and HTTP (Streamable HTTP) transports. Authentication via OAuth 2.1, bearer tokens, or API keys. MCP tools are auto-adapted to the Anthropic SDK format and can be assigned per-agent or globally.
+
+### Code Sandbox
+
+Agents can execute JavaScript in an isolated sandbox (Node.js `vm` module). No filesystem, network, or process access. 5-second default timeout, 30-second maximum. Safe globals only (Math, JSON, Date, Array, Object, Map, Set, etc.).
 
 ### Web Search
 
 Agents with web search enabled can search the web during task execution, powered by Anthropic's built-in search tool.
 
+### Local Models with Ollama
+
+If you run [Ollama](https://ollama.com) locally, the runtime routes lightweight tasks (orchestration, memory extraction) to your local model instead of Claude. The model catalog includes 25+ models across 5 memory tiers with device-aware recommendations. Complex work (planning, agent tasks, browser automation) still goes to Claude. If Ollama goes down, everything falls back to Anthropic automatically.
+
 ### Offline Mode
 
 If ohwow.fun becomes unreachable, the runtime continues with cached agent configs. Tasks still execute, results still store locally. When connectivity returns, everything syncs back up.
 
-## What Stays Local
+## Enterprise Mode
 
-The runtime syncs agent configurations from ohwow.fun and reports back only operational metadata: task titles, status, token counts, and costs. Everything else stays on your machine:
+Enterprise mode keeps your business data on your infrastructure while syncing operational metadata to the cloud dashboard.
 
+**What syncs to the cloud:**
+- Agent configurations (pulled from the dashboard)
+- Task metadata: titles, status, token counts, costs
+
+**What stays local:**
 - Prompts and system instructions
 - Agent outputs and full conversations
 - Long-term agent memory
@@ -117,29 +180,38 @@ The runtime syncs agent configurations from ohwow.fun and reports back only oper
 - WhatsApp and Telegram message history
 - Browser session data and screenshots
 
-This is the core of the Enterprise plan. Your business data never leaves your infrastructure.
-
-## Web UI
+**How it works:**
 
-The runtime also serves a web UI accessible from any browser on your network. Same capabilities as the TUI. Useful if you prefer a graphical interface or want to share access with your team locally.
+Activate with a license key from the ohwow.fun dashboard (Settings > License). The runtime connects to the control plane via long-polling, receives task dispatches, and sends back status updates. Heartbeats confirm the device is online. Each license is locked to a single device. The cloud dashboard gives you a web interface for managing agents, reviewing tasks, and monitoring your workspace without touching the terminal.
 
-## Headless Mode
+## Headless / Daemon Mode
 
-For servers, containers, or always-on deployments where you don't need a terminal interface:
+For servers, containers, or always-on deployments:
 
 ```bash
-ohwow --headless
+ohwow --daemon
 ```
 
-In headless mode, configure through environment variables. The web UI still runs normally. See the [configuration docs](https://ohwow.fun/docs/runtime/configuration) for available options.
+Runs the daemon in the foreground (no TUI). Suitable for systemd, launchd, or Docker. Set `OHWOW_HEADLESS=1` as an alternative. The web UI still runs normally. Configure through environment variables.
+
+## Configuration
+
+Config lives at `~/.ohwow/config.json`. Key environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `OHWOW_PORT` | HTTP server port (default 7700) |
+| `OHWOW_HEADLESS` | Set to `1` for headless mode |
+| `OHWOW_BROWSER_HEADLESS` | Set to `false` to show the browser |
+| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models |
 
 ## Supported Models
 
 | Model | Provider |
-|-------|----------|
+|---|---|
 | Claude Opus 4.6 | Anthropic |
-| Claude Sonnet 4.5 | Anthropic |
-| Claude Haiku 4 | Anthropic |
+| Claude Sonnet 4.6 | Anthropic |
+| Claude Haiku 4.5 | Anthropic |
 | Any Ollama model | Local |
 
 ## License