@sesamespace/hivemind 0.8.0 → 0.8.1

package/docs/TOOL-PARITY-PLAN.md

@@ -1,191 +0,0 @@
-# Hivemind Tool Parity Plan
-
-*Goal: Bring Hivemind tool capabilities to parity with OpenClaw/Pi, then beyond.*
-
-*Created: 2026-03-01 | Last updated: 2026-03-01*
-
----
-
-## Context
-
-OpenClaw uses [Pi](https://github.com/badlogic/pi-mono/) as its underlying coding agent (see [Armin's article](https://lucumr.pocoo.org/2026/1/31/pi/)). Pi provides 4 core tools: `read`, `write`, `edit`, `bash`. OpenClaw layers orchestration on top: messaging, scheduling, sub-agents, browser control, vision, TTS, device control, and more.
-
-Hivemind is a **headless messaging agent** (not a TUI coding agent like Pi), but it needs equivalent capabilities. Hivemind's competitive edge is its **3-layer semantic memory** (L2 episodic + L3 semantic), which neither Pi nor OpenClaw have.
-
-**Principle: Build, don't integrate.** Study Pi's source for inspiration, write our own implementations. No external dependency risk, tailored to our headless/messaging paradigm.
-
----
-
-## What's Already Implemented ✅
-
-### Core Tools (shipped in v0.6.0-v0.7.2)
-| Tool | Status | Notes |
-|------|--------|-------|
-| `shell` | ✅ Shipped | Workspace-scoped, configurable timeout |
-| `read_file` | ✅ Shipped | With offset/limit for large files |
-| `write_file` | ✅ Shipped | Auto-creates directories |
-| `edit_file` | ✅ Shipped | Exact-match find-and-replace |
-| `list_files` | ✅ Shipped | Directory listing |
-| `web_search` | ✅ Shipped | Brave Search API |
-| `web_fetch` | ✅ Shipped | URL → readable text |
-
-### Memory Tools (shipped in v0.7.0)
-| Tool | Status | Notes |
-|------|--------|-------|
-| `memory_search` | ✅ Shipped | L2 semantic search per context |
-| `memory_contexts` | ✅ Shipped | List all contexts |
-| `memory_l3` | ✅ Shipped | View promoted knowledge |
-| `memory_cross_search` | ✅ Shipped | Search across all contexts |
-
-### Infrastructure (shipped in v0.7.0)
-| Feature | Status | Notes |
-|---------|--------|-------|
-| Agentic tool-use loop | ✅ Shipped | OpenAI-compatible function calling via OpenRouter, max 25 iterations |
-| Tool registry | ✅ Shipped | Pluggable registration system |
-| Session persistence | ✅ Shipped | JSONL per context, survives restarts |
-| Lossless compaction | ✅ Shipped | Saves episodes to L2 before summarizing |
-| MEMORY.md | ✅ Shipped | Global + per-context agent-managed memory files |
-| Skills discovery | ✅ Shipped | Auto-scan workspace/skills/*/SKILL.md |
-| Events system | ✅ Shipped | File-based immediate/one-shot/periodic scheduling |
-| Token budget management | ✅ Shipped | Context limit + response reserve |
-| Dashboard | ✅ Shipped | Request inspector, memory browser, context overview |
-| Service install | ✅ Shipped | launchd services (agent + memory daemon + watchdog) |
-| One-line installer | ✅ Shipped | `curl -sL api.sesame.space/api/v1/hivemind/install | bash -s -- <key>` |
-
----
-
-## What's Not Implemented Yet
-
-### Tier 1 — Essential (Phase 1-2) ✅ COMPLETE
-
-| # | Tool/Feature | Status | Tools Added |
-|---|-------------|--------|------------|
-| 1 | **Event/scheduling tools** | ✅ Shipped | `create_event`, `list_events`, `delete_event` |
-| 2 | **Enhanced Sesame messaging** | ✅ Shipped | `send_message` |
-| 3 | **Sub-agent spawning** | ✅ Shipped | `spawn_agent`, `list_agents`, `kill_agent` |
-| 4 | **Web browsing** | ✅ Shipped | `browse` (extract/screenshot/click/type/evaluate) |
-
-### Tier 2 — Important (Phase 3) ✅ COMPLETE
-
-| # | Tool/Feature | Status | Tools Added |
-|---|-------------|--------|------------|
-| 5 | **Image/vision analysis** | ✅ Shipped | `analyze_image` |
-| 6 | **Git operations** | ✅ Shipped | `git_status`, `git_diff`, `git_commit`, `git_log`, `git_push` |
-| 7 | **Cross-context messaging** | ⬚ Deferred | (existing cross-context search covers most cases) |
-
-### Tier 3 — System & Mac Capabilities ✅ COMPLETE
-
-| # | Tool/Feature | Status | Tools Added |
-|---|-------------|--------|------------|
-| 8 | **System management** | ✅ Shipped | `system_info`, `process_list`, `process_kill`, `service_control`, `disk_usage`, `network_info` |
-| 9 | **macOS automation** | ✅ Shipped | `run_applescript`, `notify`, `clipboard_read`, `clipboard_write`, `open_url`, `screenshot` |
-| 10 | **Data handling** | ✅ Shipped | `sqlite_query`, `archive_create`, `archive_extract`, `pdf_extract` |
-| 11 | **HTTP server/client** | ✅ Shipped | `http_serve`, `http_stop`, `http_request` |
-| 12 | **File watching** | ✅ Shipped | `watch_start`, `watch_stop`, `watch_list` |
-
-### Tier 4 — Future (not yet implemented)
-
-| # | Tool/Feature | What It Does | Notes |
-|---|-------------|-------------|-------|
-| 13 | **Skills/extensions system** | Formalized hot-reloadable skills with tool registration | Inspired by Pi's extension system |
-| 14 | **TTS** | Text-to-speech output via API | ElevenLabs API |
-| 15 | **SSH** | Remote machine access | Could use shell + ssh CLI |
-
----
-
-## Implementation Plan
-
-### Phase 1: Event Tools + Enhanced Messaging
-**Estimate: 1-2 coding sessions**
-
-```
-packages/runtime/src/tools/
-  events.ts     — NEW: create_event, list_events, delete_event
-  messaging.ts  — NEW: send_message (to any Sesame channel/user)
-```
-
-**Event tools:** Wrap the existing `EventsWatcher` infrastructure. Agent can create one-shot (reminders) and periodic (cron-like) events. Events fire as messages processed by the agent.
-
-**Messaging tools:** Use existing Sesame SDK to send messages to arbitrary channels. Agent can proactively reach out, not just reply to incoming messages.
-
-**Dependencies:** None new. Uses existing EventsWatcher + Sesame SDK.
-
-### Phase 2: Sub-agents + Web Browsing
-**Estimate: 3-4 coding sessions**
-
-```
-packages/runtime/src/tools/
-  spawn.ts      — NEW: spawn_agent, list_agents, kill_agent
-  browser.ts    — NEW: browse_url, browser_action
-```
-
-**Sub-agents:** Fork a new agent process with `hivemind start --context <name> --task "<prompt>"`. Parent tracks child PIDs. Results reported back via Sesame message or shared file. Timeout and cleanup built in.
-
-**Web browsing:** Headless Playwright for full web interaction. Agent can navigate, click, fill forms, extract content from JS-rendered pages. Single dependency (`playwright`), but it's the right tool for this — curl/fetch can't handle SPAs, authentication flows, or dynamic content.
-
-**Why Playwright:** We considered avoiding it (heavy dep), but web browsing is a core capability for agents that need to "do anything a human can do on a computer." Pi/OpenClaw use it. The alternative (shell + curl) only handles static pages.
-
-### Phase 3: Vision + Git
-**Estimate: 1-2 coding sessions**
-
-```
-packages/runtime/src/tools/
-  vision.ts     — NEW: analyze_image
-  git.ts        — NEW: git_status, git_diff, git_commit, git_push
-```
-
-**Vision:** Single HTTP call to OpenRouter with vision-capable model. Accept image URL or base64.
-
-**Git:** Thin wrappers around git CLI with structured output. Reduces token usage vs raw `shell` git output. Safety: confirmation before push.
-
-### Phase 4: Skills/Extensions System
-**Estimate: 2-3 coding sessions**
-
-Formalize the existing skills discovery into a proper extension system:
-- Skills can register new tools dynamically
-- Hot-reload on file change (inspired by Pi's extension system)
-- Agent can write and install its own skills
-- Skills persist across restarts
-
----
-
-## Architecture Notes
-
-### Tool Registration Pattern
-All tools follow the existing registry pattern:
-```typescript
-// Each tool file exports a register function
-export function registerEventTools(registry: ToolRegistry, dataDir: string): void {
-  registry.register("create_event", description, schema, executor);
-  // ...
-}
-```
-
-### Security Model
-- **Shell:** Workspace-scoped, configurable timeout (existing)
-- **Files:** Scoped to workspace (existing)
-- **Messaging:** Authenticated via existing Sesame connection
-- **Sub-agents:** Inherit parent permissions, isolated context
-- **Events:** File-based, local only
-- **Browser:** Sandboxed Playwright instance, no persistent state
-- **Git:** Confirmation before push
-
-### What Hivemind Has That OpenClaw/Pi Don't
-- **3-layer semantic memory** (L2 episodic + L3 semantic with automatic promotion)
-- **Cross-context knowledge sharing** with isolation by default
-- **Memory-augmented responses** (every LLM call enriched with relevant history)
-- **Dashboard** for debugging LLM calls + memory state
-- **Token budget management** with configurable limits
-
-This isn't just parity — it's parity + memory, which is the competitive edge.
-
----
-
-## Superseded Documents
-
-- `TOOL-USE-DESIGN.md` (root) — Original tool architecture design. **Fully implemented** in v0.6.0-v0.7.2. Kept for historical reference.
-- `DASHBOARD-PLAN.md` (root) — Dashboard design. **Fully implemented**. Kept for reference.
-
----
-
-*This is the authoritative plan for Hivemind tool development. Update this document as phases complete.*