homaruscc 0.2.0 → 0.4.0

package/README.md

@@ -154,6 +154,8 @@ Restart Claude Code. HomarUScc's tools will appear automatically. The proxy auto
 |------|-------------|
 | `telegram_send` | Send a message to a Telegram chat |
 | `telegram_read` | Read recent incoming messages |
+| `telegram_typing` | Send a typing indicator |
+| `telegram_react` | React to a message with an emoji |
 | `memory_search` | Hybrid vector + full-text search over stored content |
 | `memory_store` | Store and index content for later retrieval |
 | `timer_schedule` | Schedule cron, interval, or one-shot timers |
@@ -189,6 +191,21 @@ When enabled, the dashboard runs on `http://localhost:3120` with:
 - Real-time event log via WebSocket
 - System status panel
 - Memory search browser
+- CRM (People) — markdown-based contact manager with search, tags, connections, and linked document viewer
+- Kanban — task board synced with the agent's task system
+
+The dashboard is responsive — on mobile devices the sidebar collapses into a hamburger menu. Accessible remotely over Tailscale at `http://<your-tailscale-ip>:3120`.
+
+### Apps Platform (planned)
+
+The dashboard supports a pluggable apps system. The agent can build mini web apps on request (budget trackers, reading lists, dashboards) that live inside the dashboard UI:
+
+- Apps live at `~/.homaruscc/apps/{slug}/` with a manifest, React component, and JSON data store
+- Each app declares hooks (`read`, `write`, `describe`) exposed via a single `app_invoke` MCP tool
+- The agent can query and update app state through hooks — "what's on my reading list?" triggers `app_invoke(slug=reading-list, hook=describe)`
+- Apps are created by the agent via filesystem tools and auto-discovered on manifest scan
+
+See `specs/apps-platform.md` and `design/crc-App*.md` for the full design.
 
 ### Dashboard Development
 
@@ -200,14 +217,18 @@ npm run dev    # Dev server on :3121, proxies API to :3120
 
 ## Runtime Directories
 
-HomarUScc creates runtime data that's gitignored and stays local:
+HomarUScc creates runtime data that's gitignored and stays local. All user data lives under `local/` (one gitignore line):
 
 | Directory | Purpose |
 |-----------|---------|
-| `user/context/` | Facts the assistant learns about you |
-| `user/corrections/` | Corrections you've made (so it doesn't repeat mistakes) |
-| `user/preferences/` | Your stated preferences |
-| `system/` | System-level learned knowledge |
+| `local/user/context/` | Facts the assistant learns about you |
+| `local/user/corrections/` | Corrections you've made (so it doesn't repeat mistakes) |
+| `local/user/preferences/` | Your stated preferences |
+| `local/system/` | System-level learned knowledge |
+| `local/crm/` | CRM contact files (markdown + YAML frontmatter, see `crm.example/`) |
+| `local/dreams/` | Dream cycle output (nightly, stored at 0.5x weight) |
+| `local/research/` | Research notes stored by memory system |
+| `local/docs/` | Private documents (outreach drafts, session notes, etc.) |
 | `~/.homaruscc/memory/` | Vector + FTS search index (SQLite) |
 | `~/.homaruscc/identity/` | Agent identity files (soul, user, state, preferences, disagreements) |
 | `~/.homaruscc/journal/` | Daily reflection journal entries (indexed by memory system) |
@@ -234,7 +255,7 @@ The `PreCompact` hook sets a flag on the backend. The next `/api/wait` response
 
 Claude Code compresses conversation history when the context window fills up. Without mitigation, the post-compaction agent loses track of what it was doing. HomarUScc handles this with two mechanisms:
 
-**Session checkpoint** — Before compaction, the agent saves its current task context (topic, recent decisions, in-progress work, modified files) to `~/.homaruscc/checkpoint.json` via `POST /api/checkpoint`. After compaction, the post-compact context injection includes this checkpoint so the new instance knows exactly where things left off. The checkpoint is cleared at session end.
+**Session checkpoint** — Before compaction, the agent saves its current task context (topic, recent decisions, in-progress work, modified files, session texture, highlight snippets) to `~/.homaruscc/checkpoint.json` via `POST /api/checkpoint`. After compaction, the post-compact context injection includes this checkpoint so the new instance knows exactly where things left off. The checkpoint is cleared at session end. The `texture` field captures the session's conversational dynamic (e.g., "rapid shipping, playful, terse messages") and `highlights` preserves 2-3 raw exchange snippets that exemplify the vibe — restoring not just _what_ was happening but _how_ it felt.
 
 **Delivery watermark** — The server tracks the timestamp of the last event delivered to Claude Code. After compaction, the event loop resumes from the watermark instead of replaying old events. This prevents the "bad loop" problem where a post-compaction agent re-handles messages it already responded to.
 
@@ -269,7 +290,7 @@ For tasks that would consume significant context (research, multi-file processin
 
 Max concurrent agents is configurable via `agents.maxConcurrent` in config (default 3). The agent registry tracks running/completed/failed agents and includes them in post-compaction context so background work isn't lost across compaction boundaries.
 
-**Completion detection:** The backend polls output files of registered agents every 5 seconds. When it detects a completion marker (stable file mtime for 10+ seconds, or `"stop_reason":"end_turn"` in the output), it emits an `agent_completed` event that wakes the main event loop. No manual checking needed — results arrive as events.
+**Completion detection:** Agents signal completion by calling `POST /api/agents/:id/complete` with a result summary. This emits an `agent_completed` event that wakes the main event loop. A 30-minute timeout fallback catches agents that fail to call back. No polling needed — results arrive as events.
 
 ## Architecture
 
@@ -286,13 +307,13 @@ Key source files:
 | `src/mcp-tools.ts` | MCP tool definitions |
 | `src/mcp-resources.ts` | MCP resource definitions |
 | `src/config.ts` | Config loader with env var resolution and hot-reload |
-| `src/telegram-adapter.ts` | Telegram long-polling adapter |
+| `src/telegram-adapter.ts` | Telegram long-polling adapter (text, photos, documents, reactions, edits) |
 | `src/dashboard-server.ts` | Express + WebSocket dashboard server |
 | `src/dashboard-adapter.ts` | Dashboard channel adapter |
 | `src/memory-index.ts` | SQLite + sqlite-vec hybrid search with dream-aware scoring |
 | `src/compaction-manager.ts` | Auto-flush memory before context compaction |
 | `src/session-checkpoint.ts` | Save/restore task context across compaction |
-| `src/agent-registry.ts` | Track background agents with capacity limits |
+| `src/agent-registry.ts` | Track background agents with callback completion and timeout fallback |
 | `src/transcript-logger.ts` | Session transcript capture and indexing |
 | `src/identity-manager.ts` | Identity loader (soul.md, user.md, state.md) |
 | `src/timer-service.ts` | Cron, interval, and one-shot timers |