From 1222f806ce2010ebe658baae46b2dc28e18819ee Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 28 Apr 2026 22:07:48 -0400 Subject: [PATCH] docs: sync all documentation to current state (2026-04-28) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HELP.md: - Replace stale "Agent Mode" section with accurate "Tools (⚡)" section including full tool table (27 tools across 9 categories) - Fix header controls table: distinguish Context & Memory panel (sliders) from Settings dropdown (☰) - Update Settings panel section: "Backend" → "Role", add S/M/L and ⌃↵ to Display controls list - Update Backends section to match Role toggle terminology TODO__Agents.md: - Mark 5 new journal tools as complete (ae_journal_list, entry_update, entry_disable, entry_append, entry_prepend) - Add completed sections for: shell_exec tool, Tools toggle decoupling, UI input area polish (2026-04-28) MASTER.md: - Date: 2026-04-27 → 2026-04-28 - Orchestrator row: "Agent mode in UI" → "⚡ Tools toggle in UI (27 tools)" CLAUDE.md: - Date: 2026-04-03 → 2026-04-28 - Add orchestrator row to Current State table - Add full 27-tool list for quick reference Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 11 +++++-- cortex/static/HELP.md | 54 ++++++++++++++++++++++------------- documentation/MASTER.md | 4 +-- documentation/TODO__Agents.md | 31 ++++++++++++++++++++ 4 files changed, 76 insertions(+), 24 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3f5191d..a27cac2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -212,9 +212,9 @@ clearly asked for a directory to be unblocked. --- -## Current State (2026-04-03) +## Current State (2026-04-28) -Cortex is running and stable. All three primary channels are live: +Cortex is running and stable. All channels are live: | Channel | Status | Notes | |---|---|---| @@ -222,9 +222,16 @@ Cortex is running and stable. All three primary channels are live: | Nextcloud Talk | ✅ Live | HMAC-signed webhook, async reply | | Google Chat | ✅ Live | Workspace Add-on, `hostAppDataAction` response format | | Local backend | ✅ Live | Open WebUI/Ollama, per-user multi-model config | +| Orchestrator | ✅ Live | Gemini API tool loop → Claude response; ⚡ toggle in UI | Active users: scott (inara, developer), holly (tina), brian (wintermute) +**27 orchestrator tools:** web_search, file_read, shell_exec, claude_allow_dir, +task_list/create/update/complete, cron_list/add/remove/toggle, +reminders_add/list/clear, scratch_read/write/append/clear, +ae_journal_list/search/entry_create/entry_update/entry_disable/entry_append/entry_prepend, +ae_task_list. + See `documentation/TODO__Agents.md` for the active task list. See `documentation/ROADMAP.md` for phases and what's next. diff --git a/cortex/static/HELP.md b/cortex/static/HELP.md index 6b9534c..bb8a6a2 100644 --- a/cortex/static/HELP.md +++ b/cortex/static/HELP.md @@ -6,7 +6,7 @@ and are appended automatically by help.html when present. --> -*Last updated: 2026-04-27* +*Last updated: 2026-04-28* --- @@ -15,21 +15,21 @@ | Button | What it does | |---|---| | **Sessions** | Open the sessions panel — list, resume, or start sessions | -| **Files** | Open the identity file editor (SOUL, MEMORY, etc.) | -| **⚙ N** | Open the Settings panel (N = current context tier) | +| **N** (sliders icon) | Open the Context & Memory panel (N = current context tier) | +| **☰** | Settings menu — Files, Account, Sign Out | | **?** | Open this help panel | -The **⚙ Settings** panel contains all configuration options: +The **Context & Memory** panel (sliders icon with tier number) contains all configuration options: | Section | Controls | |---|---| | **Context Tier** | T1 – T4 context depth | | **Memory Layers** | Toggle Long / Mid / Short memory on/off | -| **Distill Memory** | Manually trigger short / mid / long / all distillation | -| **Backend** | Active LLM backend — click to cycle: claude → gemini → local → auto | -| **Display** | Aa/A+/A− font size cycle · ☾/☀ theme toggle | +| **Distill Memory** | Manually trigger Short / Mid / Long / All distillation | +| **Role** | Active LLM role — click to cycle through configured role assignments | +| **Display** | **Aa** cycles font size · **☾** toggles theme · **S/M/L** cycles input area height · **⌃↵** toggles send shortcut | -All header settings (theme, font size, tier, memory layers) persist in `localStorage` across page refreshes. +All settings persist in `localStorage` across page refreshes. --- @@ -46,22 +46,36 @@ Each assistant response shows a small **model tag** in the bottom-right corner i --- -## Agent Mode +## Tools (⚡) -Click the **Agent** button in the input row to enable Agent mode. The button highlights and Send changes to **Run**. +Click the **⚡** button in the input row to enable the Tools toggle. When lit (amber), **Send** changes to **Run** and messages are routed through the **orchestrator** instead of directly to the chat model. -In Agent mode, messages are routed through the **orchestrator** instead of directly to the chat model: +The orchestrator runs a multi-step tool loop: -1. The **orchestrator model** runs a tool loop — searches the web, reads files, checks tasks, calls APIs as needed +1. The **orchestrator model** reasons about the request and calls tools as needed — web search, file reads, task management, shell commands, Aether Journals, and more 2. It produces an enriched summary of what it found -3. The **responder model** receives that context and writes the final user-facing reply +3. The **responder model** (set by the active Role) receives that context and writes the final user-facing reply 4. A `⚡ N tool calls: …` note appears below the response listing what was used -Which model acts as orchestrator is set in **Settings → Models → Role Assignments → Orchestrator**. By default this is Gemini API; a capable local model can be assigned instead. +The ⚡ toggle is **independent of the Role selector** — you can use any role (chat, coder, research, etc.) with or without tools. The orchestrator model is configured in **Account → Model Registry → Role Assignments → Orchestrator**. By default this is Gemini API. -Agent mode is best for tasks that require research, multi-step reasoning, or tool use (e.g. "search for X", "add a task", "what's on my list?"). Regular chat is faster for conversational turns. +**Available tools:** -Agent mode sessions persist to history exactly like regular chat. +| Category | Tools | +|---|---| +| Web | `web_search` | +| Files | `file_read` | +| Shell | `shell_exec`, `claude_allow_dir` | +| Tasks | `task_list`, `task_create`, `task_update`, `task_complete` | +| Cron | `cron_list`, `cron_add`, `cron_remove`, `cron_toggle` | +| Reminders | `reminders_add`, `reminders_list`, `reminders_clear` | +| Scratchpad | `scratch_read`, `scratch_write`, `scratch_append`, `scratch_clear` | +| Aether Journals | `ae_journal_list`, `ae_journal_search`, `ae_journal_entry_create`, `ae_journal_entry_update`, `ae_journal_entry_disable`, `ae_journal_entry_append`, `ae_journal_entry_prepend` | +| Aether Tasks | `ae_task_list` | + +Tools mode is best for tasks requiring research, multi-step reasoning, or side effects (e.g. "search for X", "add a task", "what's on my list?", "append this to my journal"). Regular chat is faster for conversational turns. + +Orchestrated sessions persist to history exactly like regular chat. --- @@ -97,11 +111,11 @@ Three backends are available: | **Gemini** | Google Gemini via the Gemini CLI | | **Local** | Any OpenAI-compatible endpoint (Open WebUI, Ollama, OpenRouter, etc.) | -The **⚙ Backend** toggle cycles: **auto → claude → gemini → local → auto** +The **Role** toggle in the Context & Memory panel cycles through configured role assignments. Each role maps to a Primary / Backup 1 / Backup 2 model chain set in the Model Registry. -- **auto** uses the model assigned to the `chat` role in your Model Registry (recommended) -- Selecting a specific backend forces that backend for all messages, regardless of role assignments -- The active model label appears below the toggle button when a specific backend is active +- The active model label appears below the toggle button +- `auto` (default) uses the model assigned to the `chat` role in your Model Registry +- Forcing a specific backend overrides the role assignment for that session If the active backend fails, a fallback is tried automatically. A **⚡** badge appears on the response when this happens. diff --git a/documentation/MASTER.md b/documentation/MASTER.md index 1e837eb..25d3420 100644 --- a/documentation/MASTER.md +++ b/documentation/MASTER.md @@ -1,7 +1,7 @@ # Cortex / Inara — Master Index > Start here. This document is a map, not a manual. -> Last updated: 2026-04-27 +> Last updated: 2026-04-28 --- @@ -23,7 +23,7 @@ Cortex is a self-hosted personal AI platform. It routes messages from any input | Claude backend | ✅ Live | Primary — via Claude Code CLI | | Gemini backend | ✅ Live | Fallback — via Gemini CLI | | Local backend | ✅ Live | Third option — Open WebUI/Ollama on scott_gaming | -| Gemini orchestrator | ✅ Live | Tool loop → Claude response, Agent mode in UI | +| Gemini orchestrator | ✅ Live | Tool loop → Claude response, ⚡ Tools toggle in UI (27 tools) | | Model registry V2 | ✅ Live | Providers (Anthropic/Google/Local), multi-account Gemini | | Memory distillation | ✅ Live | Short (daily) / Mid (weekly) / Long (monthly) | | Multi-user | ✅ Live | Scott, Holly, Brian — each with own personas | diff --git a/documentation/TODO__Agents.md b/documentation/TODO__Agents.md index 2af2b31..02ecc0c 100644 --- a/documentation/TODO__Agents.md +++ b/documentation/TODO__Agents.md @@ -36,8 +36,13 @@ See `DESIGN__Model_Registry_V2.md` for full design. ### [Intelligence] Knowledge consolidation — Phase 1 See `ARCH__Intelligence_Layer.md` for full design. +- [x] Tool: `ae_journal_list` — list all journals for the account — 2026-04-28 - [x] Tool: `ae_journal_search` — search before creating to avoid duplicates - [x] Tool: `ae_journal_entry_create` — write a new entry with source metadata +- [x] Tool: `ae_journal_entry_update` — PATCH any fields on an existing entry — 2026-04-28 +- [x] Tool: `ae_journal_entry_disable` — soft-delete via enable=false — 2026-04-28 +- [x] Tool: `ae_journal_entry_append` — read→append timestamped section→write (running logs) — 2026-04-28 +- [x] Tool: `ae_journal_entry_prepend` — read→prepend timestamped section→write (newest-first logs) — 2026-04-28 - [ ] Import script: walk a markdown directory, chunk by H2 section, create entries - [ ] Target: markdown files from `~/DgrZone_Nextcloud/` and `~/OSIT_Nextcloud/` - [ ] Tag strategy: source path, date, topic tags from frontmatter or filename @@ -99,6 +104,32 @@ base accessible to local models. Endpoints documented in `docs/OPEN_WEBUI_API.md ## ✅ Completed +### [UI] Input area polish — 2026-04-28 +- Single cycling S/M/L button replaces 3 separate height buttons (same UX as font size) +- S size collapses mode-select to a row (compact); M/L keep vertical column layout +- Input height minimum derived from setting so empty textarea reflects selected size +- Context & Memory panel and Settings dropdown are mutually exclusive (closeAllPanels fix) +- Both panels now use consistent shadow (var(--shadow)) and z-index (200) + +### [Tools] Tools toggle — decoupled from Role/Backend — 2026-04-28 +- Removed "Agent" mode from the mode selector; replaced with independent ⚡ toggle +- `toolsEnabled` persists in localStorage; routes to orchestrator regardless of active mode +- Layout: column (M/L) or row (S) driven by `data-size` attribute set by JS +- chat_role flows from UI → OrchestrateRequest → orchestrator_engine.run(response_role=...) + +### [Tools] shell_exec tool — 2026-04-28 +- `shell_exec(command, working_dir, timeout)` in `cortex/tools/system.py` +- Runs any shell command on the Cortex host; timeout clamped 1–120s +- Use for system diagnostics: `df -h`, `ps aux`, `journalctl`, `free -h`, etc. + +### [Tools] Aether Journals full toolkit — 2026-04-28 +- `ae_journal_list` — list all journals + ids for the account +- `ae_journal_entry_update` — PATCH any fields (title, content, summary, tags, enable) +- `ae_journal_entry_disable` — soft-delete via enable=false +- `ae_journal_entry_append` — read→append timestamped section→write (running/data logs) +- `ae_journal_entry_prepend` — read→prepend timestamped section→write (newest-first) +- Shared `_get_entry` / `_patch_entry` helpers; OpenAI JSON Schema auto-derived from Gemini declarations + ### [Local] Per-user multi-model local LLM settings — 2026-04-01 - `home/{username}/local_llm.json` — `hosts[]` + `models[]` + `active_model_id` structure - `cortex/user_settings.py` — CRUD functions: save_host, add_model, remove_model, set_active_model, get_active_local_model