@hybridaione/hybridclaw 0.4.3 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## [Unreleased]
 
+## [0.6.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.6.0)
+
+### Added
+
+- **Local LLM provider support**: Added Ollama, LM Studio, and vLLM as local
+  backends with `hybridclaw local configure|status`, auto-discovery of running
+  instances, health monitoring, model catalog management, thinking extraction,
+  and tool-call normalization for small local models.
+- **Session reset flow**: Added `reset [yes|no]` across gateway/TUI and Discord
+  slash commands so a session can clear history, restore per-session
+  model/chatbot/RAG defaults, and remove the active agent workspace after
+  confirmation.
+- **Activity-based agent timeout**: The IPC read timeout now resets on agent
+  activity (text deltas, tool progress) instead of using a fixed wall clock,
+  so slow local models making steady progress are not killed prematurely.
+
+### Fixed
+
+- **Host sandbox `/workspace` references**: System prompt skill locations and
+  tool guidance now use real filesystem paths when `sandbox=host` instead of
+  the container-only `/workspace` mount path that does not exist on the host.
+- **Local provider session stability**: Pooled workers now restart when backend
+  targets or auth signatures change, recreated workspaces clear stale session
+  transcript state, and missing workspace approval policies are bootstrapped
+  reliably.
+- **Session compaction budget accuracy**: Auto-compaction now counts system
+  prompt tokens instead of only message and summary tokens, so compaction
+  triggers at the configured threshold.
+- **Misleading timeout error message**: Changed "Timeout waiting for container
+  output" to "Timeout waiting for agent output" since the same IPC mechanism
+  is used by both host and container runners.
+
+## [0.5.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.5.0)
+
+### Added
+
+- **Model Context Protocol support**: Added runtime `mcpServers` config plus container MCP client loading so HybridClaw can expose configured MCP servers as namespaced tools, with TUI `/mcp list|add|toggle|remove|reconnect` management commands.
+- **Discord slash command control plane**: Added global Discord slash commands for status, approvals, compaction, channel policy, model/bot selection, RAG, Ralph loop, MCP management, usage, export, sessions, audit, and scheduling, with private approval responses.
+- **Bundled office document skills**: Added `docx`, `xlsx`, `pptx`, and `office-workflows` bundled skills plus shared office helper scripts for OOXML pack/unpack, tracked-change cleanup, spreadsheet import/recalc, and presentation thumbnail QA.
+- **Authenticated artifact downloads**: Added gateway `/api/artifact` serving for generated agent artifacts and cached Discord media so the web chat can render previews and download generated office outputs safely.
+
+### Changed
+
+- **Runtime capability guidance**: Prompt/tool summaries now group MCP tools cleanly and add office-file guardrails so models avoid fake binary placeholders and follow document QA workflows.
+- **Discord delivery workflow**: The Discord `message` tool now supports native local-file uploads via `filePath`, and runtime delivery/register flows better handle workspace files, `/discord-media-cache`, and DM-visible global slash commands.
+- **Documentation and examples**: README, runtime docs, and built-in web/chat surfaces now document MCP setup, bundled office skills, and artifact handling for the new workflows.
+
 ## [0.4.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.4.3)
 
 ### Added

package/README.md

@@ -61,6 +61,9 @@ hybridclaw gateway
 # Or run gateway in foreground in this terminal
 hybridclaw gateway start --foreground
 
+# For stdio MCP servers that rely on host tools like `docker` or `npx`
+hybridclaw gateway start --foreground --sandbox=host
+
 # If DISCORD_TOKEN is set, gateway auto-connects to Discord.
 
 # Start terminal adapter (optional, in a second terminal)
@@ -142,16 +145,171 @@ HybridClaw creates `~/.hybridclaw/config.json` on first run and hot-reloads most
 - HybridClaw does not keep runtime state in the current working directory. If `./.env` exists, supported secrets are migrated once into `~/.hybridclaw/credentials.json`.
 - `container.*` controls execution isolation, including `sandboxMode`, `memory`, `memorySwap`, `cpus`, `network`, `binds`, and additional mounts.
 - Use `container.binds` for explicit host-to-container mounts in `host:container[:ro|rw]` format. Mounted paths appear inside the sandbox under `/workspace/extra/<container>`.
+- `mcpServers.*` declares Model Context Protocol servers that HybridClaw connects to per session and exposes as namespaced tools (`server__tool`).
+- `mcpServers.*.env` and `mcpServers.*.headers` are currently written to `~/.hybridclaw/config.json` as plain text. Use low-privilege tokens only, set `chmod 700 ~/.hybridclaw && chmod 600 ~/.hybridclaw/config.json`, and prefer `host` sandbox mode for stdio MCP servers that depend on host-installed tools.
 - Keep HybridAI secrets in `~/.hybridclaw/credentials.json` (`HYBRIDAI_API_KEY` required for HybridAI models, `DISCORD_TOKEN` optional). Codex OAuth sessions are stored separately in `~/.hybridclaw/codex-auth.json`.
 - Trust-model acceptance is stored in `~/.hybridclaw/config.json` under `security.*` and is required before runtime starts.
 - See [TRUST_MODEL.md](./TRUST_MODEL.md) for onboarding acceptance policy and [SECURITY.md](./SECURITY.md) for technical security guidelines.
 - For contributor workflow, see [CONTRIBUTING.md](./CONTRIBUTING.md). For deeper runtime, skills, release, and maintainer reference docs, see [docs/development/README.md](./docs/development/README.md).
 
+## Local Provider Quickstart (LM Studio Example)
+
+If LM Studio is running locally and serving `qwen/qwen3.5-9b` on
+`http://127.0.0.1:1234`, use this setup:
+
+1. Configure HybridClaw for LM Studio:
+
+```bash
+hybridclaw local configure lmstudio qwen/qwen3.5-9b --base-url http://127.0.0.1:1234
+```
+
+This enables local providers, enables the LM Studio backend, normalizes the
+URL to `http://127.0.0.1:1234/v1`, and sets the default model to
+`lmstudio/qwen/qwen3.5-9b`.
+
+2. Restart the gateway in host sandbox mode:
+
+```bash
+hybridclaw gateway restart --foreground --sandbox=host
+```
+
+If the gateway is not running yet, use:
+
+```bash
+hybridclaw gateway start --foreground --sandbox=host
+```
+
+3. Check that HybridClaw can see LM Studio:
+
+```bash
+hybridclaw gateway status
+```
+
+Look for `localBackends.lmstudio.reachable: true`.
+
+You can also inspect the saved local backend config directly:
+
+```bash
+hybridclaw local status
+```
+
+4. Start the TUI:
+
+```bash
+hybridclaw tui
+```
+
+In the TUI, run:
+
+```text
+/model list
+/model set lmstudio/qwen/qwen3.5-9b
+/model info
+```
+
+Then send a normal prompt.
+
+If you want to configure the backend without changing your global default model,
+use:
+
+```bash
+hybridclaw local configure lmstudio qwen/qwen3.5-9b --base-url http://127.0.0.1:1234 --no-default
+```
+
+Other backends use the same flow:
+
+```bash
+hybridclaw local configure ollama llama3.2
+hybridclaw local configure vllm mistralai/Mistral-7B-Instruct-v0.3 --base-url http://127.0.0.1:8000 --api-key secret
+```
+
+Restart the gateway in `--sandbox=host`, then confirm reachability with
+`hybridclaw gateway status`.
+
+Notes:
+
+- LM Studio often shows its server as `http://127.0.0.1:1234`, but HybridClaw
+  should be configured with `http://127.0.0.1:1234/v1`.
+- Qwen models on LM Studio use the OpenAI-compatible `/v1` API with Qwen tool
+  and thinking compatibility enabled automatically.
+- For agent mode, load at least `16k` context in LM Studio. `32k` is the safer
+  default for longer sessions and tool use.
+- The TUI `/model` picker and Discord `/model` slash command choices are built
+  from the live gateway model list, so restart the gateway after enabling a new
+  local backend or loading a different local model.
+
+## TUI MCP Quickstart
+
+For stdio MCP servers that use host binaries such as `docker`, `node`, or
+`npx`, start the gateway in host mode:
+
+```bash
+hybridclaw gateway start --foreground --sandbox=host
+hybridclaw tui
+```
+
+In the TUI, use the MCP slash commands directly:
+
+```text
+/mcp list
+/mcp add filesystem {"transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/Users/you/project"],"enabled":true}
+/mcp toggle filesystem
+/mcp reconnect filesystem
+/mcp remove filesystem
+```
+
+Once a server is enabled, its tools appear in prompts as namespaced tool names
+such as `filesystem__read_file` or `github__list_issues`.
+
 ## Bundled Skills
 
 - `pdf` is bundled and supports text extraction, page rendering, fillable form inspection/filling, and non-fillable overlay workflows.
+- `xlsx` is bundled for spreadsheet creation, formula-safe editing, CSV/TSV cleanup, and LibreOffice-backed recalculation.
+- `docx` is bundled for Word document creation plus OOXML unpack/edit/pack workflows, comments, and tracked-change cleanup.
+- `pptx` is bundled for presentation creation with `pptxgenjs`, template-preserving OOXML edits, and thumbnail-based visual QA.
+- `office-workflows` is bundled for cross-format tasks such as CSV to XLSX cleanup and XLSX to PPTX or DOCX deliverables coordinated with delegation.
 - Use `hybridclaw skill list` to inspect available installers and `hybridclaw skill install pdf [install-id]` when a bundled skill advertises optional setup helpers.
 
+## Optional Office Dependencies
+
+When you run HybridClaw in the default container sandbox, the bundled office image already includes the main office tooling. These installs matter primarily for `--sandbox=host` workflows or when you want the same capabilities on your local machine.
+
+What they unlock:
+
+- LibreOffice (`soffice`) enables Office-to-PDF export, PPTX visual QA, and XLSX formula recalculation.
+- Poppler (`pdftoppm`) enables slide/page thumbnail rendering for PPTX visual QA.
+- Pandoc improves document conversion workflows around DOCX and Markdown.
+
+macOS:
+
+```bash
+brew install --cask libreoffice
+brew install poppler pandoc
+```
+
+Ubuntu / Debian:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y libreoffice poppler-utils pandoc
+```
+
+Fedora:
+
+```bash
+sudo dnf install -y libreoffice poppler-utils pandoc
+```
+
+Verify availability:
+
+```bash
+sh -lc 'command -v soffice >/dev/null 2>&1 || command -v libreoffice >/dev/null 2>&1 && echo soffice_ok'
+sh -lc 'command -v pdftoppm >/dev/null 2>&1 && echo pdftoppm_ok'
+sh -lc 'command -v pandoc >/dev/null 2>&1 && echo pandoc_ok'
+```
+
+Without these tools, the office skills still create and edit `.docx`, `.xlsx`, and `.pptx` files, but some higher-quality QA and conversion paths are skipped.
+
 ## Commands
 
 CLI runtime commands:
@@ -163,8 +321,11 @@ CLI runtime commands:
 - `hybridclaw gateway status` — Show lifecycle/API status
 - `hybridclaw gateway <command...>` — Send a command to a running gateway (for example `sessions`, `bot info`)
 - `hybridclaw gateway compact` — Archive older session history into semantic memory while preserving a recent active context tail
+- `hybridclaw gateway reset [yes|no]` — Clear session history, reset per-session model/chatbot/RAG settings, and remove the current agent workspace (confirmation required)
 - `hybridclaw tui` — Start terminal client connected to gateway
 - `hybridclaw onboarding` — Run HybridAI account/API key onboarding
+- `hybridclaw local status` — Show current local backend config and default model
+- `hybridclaw local configure <backend> <model-id> [--base-url <url>] [--api-key <key>] [--no-default]` — Enable and configure a local backend
 - `hybridclaw hybridai login [--device-code|--browser|--import]` — Store HybridAI API credentials via browser-assisted, headless/manual, or env-import flows
 - `hybridclaw hybridai status` — Show stored HybridAI auth state, token mask, and source
 - `hybridclaw hybridai logout` — Clear stored HybridAI credentials
@@ -177,13 +338,14 @@ CLI runtime commands:
 - `hybridclaw audit ...` — Verify and inspect structured audit trail (`recent`, `search`, `approvals`, `verify`, `instructions`)
 - `hybridclaw audit instructions [--sync]` — Compare runtime instruction copies under `~/.hybridclaw/instructions/` against installed sources and restore shipped defaults when needed
 
-In Discord, use `!claw help` to see all commands. Key ones:
+In Discord, use `!claw help` or the slash commands. Key ones:
 
 - `!claw <message>` — Talk to the agent
 - `!claw bot set <id>` — Set chatbot for this channel
 - `!claw model set <name>` — Set model for this channel
 - `!claw rag on/off` — Toggle RAG
 - `!claw compact` — Archive older history into session memory and keep a recent working tail
+- `/reset` or `!claw reset` — Clear history, reset per-session model/bot settings, and remove the current agent workspace (confirmation required)
 - `!claw clear` — Clear conversation history
 - `!claw audit recent [n]` — Show recent structured audit events
 - `!claw audit verify [sessionId]` — Verify audit hash chain integrity
@@ -191,8 +353,11 @@ In Discord, use `!claw help` to see all commands. Key ones:
 - `!claw audit approvals [n] [--denied]` — Show policy approval decisions
 - `!claw usage [summary|daily|monthly|model [daily|monthly] [agentId]]` — Show token/cost aggregates
 - `!claw export session [sessionId]` — Export session snapshot as JSONL
+- `!claw mcp list` — List configured MCP servers
+- `!claw mcp add <name> <json>` — Add or update an MCP server config
 - `!claw schedule add "<cron>" <prompt>` — Add cron scheduled task
 - `!claw schedule add at "<ISO time>" <prompt>` — Add one-shot task
 - `!claw schedule add every <ms> <prompt>` — Add interval task
 
-In the TUI, use `/compact` to trigger the same session compaction flow.
+In the TUI, use `/compact` for session compaction, `/reset` for the confirmed
+workspace reset flow, and `/mcp ...` for runtime MCP management.

package/config.example.json

@@ -1,5 +1,5 @@
 {
-  "version": 7,
+  "version": 9,
   "security": {
     "trustModelAccepted": false,
     "trustModelAcceptedAt": "",
@@ -81,6 +81,36 @@
       "openai-codex/gpt-5.1-codex-mini"
     ]
   },
+  "local": {
+    "backends": {
+      "ollama": {
+        "enabled": true,
+        "baseUrl": "http://127.0.0.1:11434"
+      },
+      "lmstudio": {
+        "enabled": false,
+        "baseUrl": "http://127.0.0.1:1234/v1"
+      },
+      "vllm": {
+        "enabled": false,
+        "baseUrl": "http://127.0.0.1:8000/v1",
+        "apiKey": ""
+      }
+    },
+    "discovery": {
+      "enabled": true,
+      "intervalMs": 300000,
+      "maxModels": 200,
+      "concurrency": 8
+    },
+    "healthCheck": {
+      "enabled": true,
+      "intervalMs": 60000,
+      "timeoutMs": 5000
+    },
+    "defaultContextWindow": 128000,
+    "defaultMaxTokens": 8192
+  },
   "container": {
     "sandboxMode": "container",
     "image": "hybridclaw-agent",
@@ -94,6 +124,33 @@
     "maxOutputBytes": 10485760,
     "maxConcurrent": 5
   },
+  "mcpServers": {
+    "filesystem": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/absolute/path/to/a/workspace"
+      ],
+      "enabled": false
+    },
+    "tavily": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "tavily-mcp@latest"],
+      "env": {
+        "TAVILY_API_KEY": "replace-me"
+      },
+      "enabled": false
+    },
+    "playwright": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "enabled": false
+    }
+  },
   "web": {
     "search": {
       "provider": "auto",

package/container/Dockerfile

@@ -1,7 +1,8 @@
 FROM node:20-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    ripgrep git curl python3 python3-pip poppler-utils qpdf \
+    ripgrep git curl python3 python3-pip poppler-utils qpdf pandoc \
+    libreoffice-calc libreoffice-impress libreoffice-writer \
     && rm -rf /var/lib/apt/lists/*
 
 RUN python3 -m pip install --no-cache-dir --break-system-packages \
@@ -12,6 +13,14 @@ RUN python3 -m pip install --no-cache-dir --break-system-packages \
     reportlab==4.4.4 \
     pillow==11.3.0
 
+RUN npm install -g \
+    docx@9.5.1 \
+    pptxgenjs@4.0.1 \
+    exceljs@4.4.0 \
+    csv-parse@6.1.0 \
+    iconv-lite@0.7.0
+ENV NODE_PATH=/usr/local/lib/node_modules:/app/node_modules
+
 WORKDIR /app
 
 COPY package.json tsconfig.json ./