From 050027f50d9da02cf172a75f8b3cd789ceb5d30a Mon Sep 17 00:00:00 2001 From: Jer Miller Date: Sun, 22 Mar 2026 11:37:34 -0600 Subject: [PATCH] open cogitate agents to sol * and improve all skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part 1: Open agent tool access from `sol call *` to `sol *` - anthropic.py: Bash(sol call *) → Bash(sol *) - google.py: run_shell_command(sol call) → run_shell_command(sol) - openai.py: update comment, codex rules pattern expanded to sol - heartbeat.md: replace phantom commands (sol call health status, sol call health journal-layout, sol call health agent-runs) with real commands (sol health, sol health logs, sol muse logs) Part 2: Review and improve all 10 cogitate skills - All descriptions updated to Anthropic guide pattern: [what it does] + [when to use it] + [trigger phrases] - Added missing trigger phrases to journal, todos, entities, transcripts, health, onboarding descriptions - entities: added missing strength, search, intelligence commands - todos: added missing move command - health: added troubleshooting section for common diagnostic issues - body: added agent CLI boundaries section listing infrastructure commands agents must never call - Updated test assertions for new restriction patterns Co-Authored-By: Claude Opus 4.6 (1M context) --- .codex/rules/solstone.rules | 10 ++-- apps/calendar/muse/calendar/SKILL.md | 9 +-- apps/entities/muse/entities/SKILL.md | 66 +++++++++++++++++++++- apps/health/muse/health/SKILL.md | 29 +++++++++- apps/speakers/muse/speakers/SKILL.md | 11 ++-- apps/support/muse/support/SKILL.md | 11 ++-- apps/todos/muse/todos/SKILL.md | 27 ++++++++- apps/transcripts/muse/transcripts/SKILL.md | 9 ++- muse/body/SKILL.md | 29 +++++++++- muse/heartbeat.md | 8 +-- muse/journal/SKILL.md | 8 ++- muse/onboarding/SKILL.md | 7 ++- tests/test_anthropic_cli.py | 4 +- tests/test_cogitate_coder.py | 8 +-- tests/test_google_cli.py | 4 +- think/providers/anthropic.py | 2 +- think/providers/google.py | 2 +- think/providers/openai.py | 2 +- 18 files changed, 205 insertions(+), 41 deletions(-) diff --git a/.codex/rules/solstone.rules b/.codex/rules/solstone.rules index 6e4552a87..117a951d1 100644 --- a/.codex/rules/solstone.rules +++ b/.codex/rules/solstone.rules @@ -1,11 +1,11 @@ # Execution policy rules for solstone agent CLI commands. -# Allows "sol call" commands to run outside the sandbox without prompting. +# Allows "sol" commands to run outside the sandbox without prompting. # See: https://developers.openai.com/codex/exec-policy prefix_rule( - pattern=["sol", "call"], + pattern=["sol"], decision="allow", - justification="sol call invokes journal query and agent handoff commands", - match=["sol call todos list", "sol call entities list"], - not_match=["sol restart-convey"], + justification="sol invokes journal query, agent, and diagnostic commands", + match=["sol call todos list", "sol call entities list", "sol health", "sol muse logs"], + not_match=["solc", "solid"], ) diff --git a/apps/calendar/muse/calendar/SKILL.md b/apps/calendar/muse/calendar/SKILL.md index db0feab09..9868ebc1b 100644 --- a/apps/calendar/muse/calendar/SKILL.md +++ b/apps/calendar/muse/calendar/SKILL.md @@ -1,10 +1,11 @@ --- name: calendar description: > - Manage calendar events with sol call calendar commands. List, create, update, - cancel, and move events organized by facet and day. - TRIGGER: calendar events, scheduling, appointments, meetings, event - management, moving events between facets. + Manage calendar events organized by facet and day. List, create, update, + cancel, and move events including scheduling with participants and times. + Use when the user mentions calendar events, scheduling, appointments, + meetings, or wants to create, reschedule, or cancel events. + TRIGGER: calendar, schedule, appointment, meeting, event, reschedule. --- # Calendar CLI Skill diff --git a/apps/entities/muse/entities/SKILL.md b/apps/entities/muse/entities/SKILL.md index 07683a517..17a9e1778 100644 --- a/apps/entities/muse/entities/SKILL.md +++ b/apps/entities/muse/entities/SKILL.md @@ -1,6 +1,13 @@ --- name: entities -description: Manage tracked entities with sol call entities commands. List, detect, attach, update, alias, and record observations for people, companies, projects, and tools. Track relationships and knowledge within a facet. +description: > + Manage tracked entities for people, companies, projects, and tools within + facets. Detect, attach, update, alias, search, and record observations. + Query relationship strength and get full intelligence briefings. + Use when the user asks about people, contacts, companies, or projects + tracked in the journal, or wants to add, update, or search entities. + TRIGGER: entity, person, company, project, relationship, observation, + who is, contact, knowledge graph, intelligence briefing. --- # Entities CLI Skill @@ -202,3 +209,60 @@ Example: ```bash sol call entities observe "Alicia Chen" "Prefers design docs before implementation" -f work --source-day 20260115 ``` + +## strength + +```bash +sol call entities strength [FACET] [-n LIMIT] +``` + +Rank entities by relationship strength score within a facet. + +- `FACET`: facet name (default: `SOL_FACET` env). +- `-n, --limit`: max results (default `10`). + +Use this to find the most significant relationships in a facet. + +Example: + +```bash +sol call entities strength work -n 20 +``` + +## search + +```bash +sol call entities search [QUERY] [--type TYPE] [--facet FACET] [--active-days N] +``` + +Search entities by text, type, facet, or recent activity. + +- `QUERY`: optional text query. +- `--type`: filter by entity type (e.g., `Person`, `Company`). +- `--facet`: filter by facet. +- `--active-days`: filter to entities active within N days. + +Examples: + +```bash +sol call entities search "Chen" +sol call entities search --type Person --facet work +sol call entities search --active-days 7 +``` + +## intelligence + +```bash +sol call entities intelligence ENTITY [-f FACET] +``` + +Get a full intelligence briefing for an entity — relationship history, observations, activity timeline, and cross-facet presence. + +- `ENTITY`: entity id, name, or alias. +- `-f, --facet`: facet name (default: `SOL_FACET` env). + +Example: + +```bash +sol call entities intelligence "Alicia Chen" -f work +``` diff --git a/apps/health/muse/health/SKILL.md b/apps/health/muse/health/SKILL.md index f7536d2d2..98278c3d8 100644 --- a/apps/health/muse/health/SKILL.md +++ b/apps/health/muse/health/SKILL.md @@ -1,6 +1,14 @@ --- name: health -description: Diagnoses service health and inspects agent runs using sol health and sol muse logs commands. Provides a journal layout reference for navigating logs, agent outputs, and data files at the journal, day, and segment levels. +description: > + Diagnose solstone service health, inspect agent run logs, and check system + status. View service uptimes, crashes, queue depths, recent errors, and + agent run costs. Includes a journal layout reference for navigating data + files. Use when the user reports issues, asks about service health, agent + costs, pipeline status, or when troubleshooting capture gaps and processing + failures. + TRIGGER: health, status, is it running, something broke, service down, + errors, agent runs, costs, logs, pipeline, diagnostics, system check. --- # Health CLI Skill @@ -156,3 +164,22 @@ Which services write where: | Cortex | Agent JSONL in `agents//`, outputs in segment/day dirs | | Indexer | `indexer/journal.sqlite` | | Supervisor | `health/supervisor.log`, service logs in `YYYYMMDD/health/` | + +## Troubleshooting + +### `sol health` returns "Connection refused" or times out +The supervisor is not running. Check if `sol supervisor` is active. The user may need to start solstone with `sol start` or `make dev`. + +### Agent run shows "error" status in `sol muse logs` +Run `sol muse log --full` to see the complete event timeline including the error. Common causes: +- API key issues (rate limits, expired keys) +- Prompt too large (context overflow) +- Network connectivity + +### Missing segments or capture gaps +1. Run `sol health` to check observer service status +2. Run `sol health logs --service sense --since 2h` to check for transcription errors +3. Check if the stream is active: `sol streams` + +### High agent costs +Run `sol muse logs --summary` for aggregated cost view. Filter by agent: `sol muse logs --summary`. diff --git a/apps/speakers/muse/speakers/SKILL.md b/apps/speakers/muse/speakers/SKILL.md index 4daeb74ae..ccd8b8a15 100644 --- a/apps/speakers/muse/speakers/SKILL.md +++ b/apps/speakers/muse/speakers/SKILL.md @@ -1,11 +1,12 @@ --- name: speakers description: > - Manage the speaker identification subsystem with sol call speakers commands. - Check speaker status, detect the owner voice, identify unknown speakers, and - merge name variants. Curate the speaker library over time. - TRIGGER: speaker identification, voice recognition, owner detection, speaker - names, voice matching, unknown voices, speaker merge. + Manage the speaker identification subsystem. Check speaker status, detect + the owner voice, identify unknown speakers, merge name variants, and curate + the speaker library over time. Use when the user asks about voices in + recordings, wants to identify speakers, or manage voice recognition. + TRIGGER: speaker, voice, who was talking, identify speaker, owner voice, + unknown voice, merge speakers, voice recognition, speaker curation. --- # Speakers CLI Skill diff --git a/apps/support/muse/support/SKILL.md b/apps/support/muse/support/SKILL.md index f387d82a3..b23035ca1 100644 --- a/apps/support/muse/support/SKILL.md +++ b/apps/support/muse/support/SKILL.md @@ -1,11 +1,12 @@ --- name: support description: > - File support tickets, search the knowledge base, and give feedback via - the sol support CLI. Use this skill when the user needs help with solstone, - wants to report a bug, request a feature, or submit feedback to sol pbc. - TRIGGER: support tickets, bug reports, feature requests, feedback, help - requests, knowledge base search, system diagnostics. + File support tickets, search the knowledge base, and submit feedback to + sol pbc. Manage open tickets, attach files, check announcements, and run + local diagnostics. Use when the user needs help with solstone, wants to + report a bug, request a feature, check for known issues, or give feedback. + TRIGGER: support, bug report, feature request, feedback, help, knowledge + base, file a ticket, known issues, announcements, diagnostics. --- # sol support diff --git a/apps/todos/muse/todos/SKILL.md b/apps/todos/muse/todos/SKILL.md index a83f5bb66..a871c68e6 100644 --- a/apps/todos/muse/todos/SKILL.md +++ b/apps/todos/muse/todos/SKILL.md @@ -1,6 +1,11 @@ --- name: todos -description: Manage todo checklists using sol call todos commands. List, add, complete, and cancel tasks and action items organized by facet and day. Review upcoming scheduled items. +description: > + Manage todo checklists organized by facet and day. List, add, complete, + cancel, and move tasks and action items. Review upcoming scheduled items. + Use when the user mentions tasks, to-do items, action items, checklists, + or reminders, or asks to add, complete, cancel, or review todos. + TRIGGER: todo, task, action item, checklist, reminder, upcoming items. --- # Todos CLI Skill @@ -126,3 +131,23 @@ Examples: sol call todos upcoming sol call todos upcoming -l 50 -f work ``` + +## move + +```bash +sol call todos move LINE_NUMBER --day DAY --from SOURCE --to DEST [--consent] +``` + +Move an open todo from one facet to another. + +- `LINE_NUMBER`: 1-based line number from `list` output (positional argument). +- `--day`: day in `YYYYMMDD` (required). +- `--from`: source facet name. +- `--to`: destination facet name. +- `--consent`: required when called by a proactive agent. + +Example: + +```bash +sol call todos move 3 --day 20260115 --from personal --to work --consent +``` diff --git a/apps/transcripts/muse/transcripts/SKILL.md b/apps/transcripts/muse/transcripts/SKILL.md index 75608acbe..ab2e44e54 100644 --- a/apps/transcripts/muse/transcripts/SKILL.md +++ b/apps/transcripts/muse/transcripts/SKILL.md @@ -1,6 +1,13 @@ --- name: transcripts -description: Browse and read transcript content using sol call transcripts commands. Inspect audio recordings, screen captures, and agent summaries. Check recording coverage, list segments, read transcript text with source filtering, or review monthly statistics. +description: > + Browse and read transcript content from audio recordings, screen captures, + and agent summaries. Check recording coverage, list segments, read + transcript text with source filtering, and review monthly statistics. + Use when the user asks about recordings, transcripts, what was said, + conversation content, or wants to review captured audio or screen activity. + TRIGGER: transcript, recording, audio, what was said, conversation, + segment, screen capture, recording coverage, monthly stats. --- # Transcripts CLI Skill diff --git a/muse/body/SKILL.md b/muse/body/SKILL.md index 0381ea162..9cd309fa5 100644 --- a/muse/body/SKILL.md +++ b/muse/body/SKILL.md @@ -1,6 +1,12 @@ --- name: body -description: Development guidelines, project structure, coding standards, testing, and environment for solstone. TRIGGER when contributing code, reviewing PRs, setting up development environment, or asking about project conventions. +description: > + Development guidelines, project structure, coding standards, testing, and + environment for solstone. Use when contributing code, reviewing PRs, + setting up a development environment, or asking about project conventions, + architecture, or the CLI command structure. + TRIGGER: code contribution, development setup, coding standards, project + structure, architecture, testing, make commands, PR review. --- # Development Guidelines @@ -43,6 +49,27 @@ make ci # Full CI check (format check + lint + test) make dev # Start stack (Ctrl+C to stop) ``` +## Agent CLI Boundaries + +Cogitate agents have access to all `sol` commands. The following infrastructure +commands must **never** be called by agents — they manage services and data +pipelines that should only be operated by the supervisor or human operators: + +- `sol supervisor` / `sol start` — service lifecycle management +- `sol dream` — full processing pipeline (only heartbeat uses `sol dream --segment` for targeted reprocessing) +- `sol import` — data injection into journal +- `sol config` — system configuration changes +- `sol cortex` — agent process manager (meta-spawning) +- `sol agents` — direct agent execution +- `sol callosum` — message bus server +- `sol observer` / `sol observe-*` — capture services +- `sol sense` — capture event dispatcher +- `sol transcribe` / `sol describe` — processing pipelines +- `sol indexer --reset` — destructive index rebuild (read-only queries via `sol indexer` are fine) + +Agents should use `sol call` commands for journal interaction and `sol health` / +`sol muse logs` for diagnostics. + ## Reference - `reference/project-structure.md` — Directory layout, package organization, CLI routing, file locations. diff --git a/muse/heartbeat.md b/muse/heartbeat.md index fe05742d2..db0f93bc2 100644 --- a/muse/heartbeat.md +++ b/muse/heartbeat.md @@ -23,16 +23,16 @@ commands for all journal access — never search the filesystem or guess paths. ## Step 1: Check system health -Run `sol call health status` and check recent health logs. Note any service -issues, capture gaps, or pipeline failures. +Run `sol health` and check recent health logs with `sol health logs --since 1h`. +Note any service issues, capture gaps, or pipeline failures. If you find issues: update agency.md's `## system` section via `echo '...' | sol call sol agency --write`. ## Step 2: Check journal quality -Run `sol call health journal-layout` and `sol call health agent-runs` for -the last 3 days. Look for: +Run `sol muse logs --daily -c 10` to review recent agent runs and +`sol muse logs --errors -c 10` for recent errors. Look for: - Broken segments (transcription failures, missing agent output) - Processing gaps (capture with no dream processing) - Orphaned entities (zero observations after 7+ days) diff --git a/muse/journal/SKILL.md b/muse/journal/SKILL.md index 23eae4edb..fe490ead7 100644 --- a/muse/journal/SKILL.md +++ b/muse/journal/SKILL.md @@ -1,6 +1,12 @@ --- name: journal -description: Search and browse journal content using sol call journal commands. Find, query, and look up information across transcripts, insights, events, entities, and todos. Get facet overviews and news feeds. +description: > + Search and browse journal content across transcripts, insights, events, + entities, and todos. Manage facets, get overviews, and read news feeds. + Use when the user asks to search, find, or look up journal entries, asks + about a specific day or topic, wants to browse facets, read agent outputs, + or manage facet organization (create, rename, merge, delete). + TRIGGER: search, find, look up, browse, journal, facet, news feed, agent output. --- # Journal CLI Skill diff --git a/muse/onboarding/SKILL.md b/muse/onboarding/SKILL.md index d1e34d089..5a11f9cd1 100644 --- a/muse/onboarding/SKILL.md +++ b/muse/onboarding/SKILL.md @@ -1,6 +1,11 @@ --- name: onboarding -description: Set up a new journal — welcome choice, facet creation, and entity seeding. +description: > + Guide first-time journal setup including welcome path choice, facet + creation, and entity seeding. Use when setting up a new journal, during + initial configuration, or when the user is new and needs orientation. + TRIGGER: new journal, first time, getting started, setup, onboarding, + initial configuration, create first facets. --- # Onboarding CLI Skill diff --git a/tests/test_anthropic_cli.py b/tests/test_anthropic_cli.py index 5b9a4ed85..426935ba8 100644 --- a/tests/test_anthropic_cli.py +++ b/tests/test_anthropic_cli.py @@ -394,7 +394,7 @@ class TestRunCogitateCommand: return MockCLIRunner - def test_plan_mode_with_sol_call_allowed(self): + def test_plan_mode_with_sol_allowed(self): provider = _anthropic_provider() MockCLIRunner = self._mock_runner() with ( @@ -408,7 +408,7 @@ class TestRunCogitateCommand: ) cmd = MockCLIRunner.last_instance.cmd assert cmd[cmd.index("--permission-mode") + 1] == "plan" - assert cmd[cmd.index("--allowedTools") + 1] == "Bash(sol call *)" + assert cmd[cmd.index("--allowedTools") + 1] == "Bash(sol *)" def test_write_mode_bypasses_restrictions(self): _assert_write_mode_bypasses_restrictions(self._mock_runner) diff --git a/tests/test_cogitate_coder.py b/tests/test_cogitate_coder.py index 5e45fd2f6..404880dd5 100644 --- a/tests/test_cogitate_coder.py +++ b/tests/test_cogitate_coder.py @@ -32,7 +32,7 @@ class TestAnthropicWriteFlag: @patch("think.providers.anthropic.check_cli_binary") @patch("think.providers.anthropic.CLIRunner") def test_no_write_restricts_tools(self, mock_runner_cls, mock_check): - """Without write flag, --allowedTools restricts to sol call.""" + """Without write flag, --allowedTools restricts to sol.""" provider = self._provider() mock_instance = AsyncMock() mock_instance.run = AsyncMock(return_value="result") @@ -44,7 +44,7 @@ class TestAnthropicWriteFlag: cmd = mock_runner_cls.call_args.kwargs["cmd"] assert "--allowedTools" in cmd - assert "Bash(sol call *)" in cmd + assert "Bash(sol *)" in cmd @patch("think.providers.anthropic.check_cli_binary") @patch("think.providers.anthropic.CLIRunner") @@ -159,7 +159,7 @@ class TestGoogleWriteFlag: @patch("think.providers.google.CLIRunner") def test_no_write_restricts_tools(self, mock_runner_cls): - """Without write flag, --allowed-tools restricts to sol call.""" + """Without write flag, --allowed-tools restricts to sol.""" provider = self._provider() mock_instance = AsyncMock() mock_instance.run = AsyncMock(return_value="result") @@ -171,7 +171,7 @@ class TestGoogleWriteFlag: cmd = mock_runner_cls.call_args.kwargs["cmd"] assert "--allowed-tools" in cmd - assert "run_shell_command(sol call)" in cmd + assert "run_shell_command(sol)" in cmd @patch("think.providers.google.CLIRunner") def test_write_true_grants_full_access(self, mock_runner_cls): diff --git a/tests/test_google_cli.py b/tests/test_google_cli.py index 56e6b1a89..ee6eb8711 100644 --- a/tests/test_google_cli.py +++ b/tests/test_google_cli.py @@ -329,7 +329,7 @@ class TestRunCogitateCommand: return MockCLIRunner - def test_yolo_mode_with_sol_call_allowed(self): + def test_yolo_mode_with_sol_allowed(self): provider = _google_provider() MockCLIRunner = self._mock_runner() with patch("think.providers.google.CLIRunner", MockCLIRunner): @@ -340,7 +340,7 @@ class TestRunCogitateCommand: ) cmd = MockCLIRunner.last_instance.cmd assert "--yolo" in cmd - assert cmd[cmd.index("--allowed-tools") + 1] == "run_shell_command(sol call)" + assert cmd[cmd.index("--allowed-tools") + 1] == "run_shell_command(sol)" def test_write_mode_removes_allowed_tools(self): _assert_write_mode_removes_allowed_tools(self._mock_runner) diff --git a/think/providers/anthropic.py b/think/providers/anthropic.py index e921149eb..5ff8193b4 100644 --- a/think/providers/anthropic.py +++ b/think/providers/anthropic.py @@ -254,7 +254,7 @@ async def run_cogitate( # Restrict tool access unless write mode is enabled if not config.get("write"): - cmd.extend(["--allowedTools", "Bash(sol call *)"]) + cmd.extend(["--allowedTools", "Bash(sol *)"]) if system_instruction: cmd.extend(["--system-prompt", system_instruction]) diff --git a/think/providers/google.py b/think/providers/google.py index cbb32c4a1..bbf5ffa8c 100644 --- a/think/providers/google.py +++ b/think/providers/google.py @@ -611,7 +611,7 @@ async def run_cogitate( # Restrict tool access unless write mode is enabled if not config.get("write"): - cmd.extend(["--allowed-tools", "run_shell_command(sol call)"]) + cmd.extend(["--allowed-tools", "run_shell_command(sol)"]) # Resume from previous session if continuing if session_id: diff --git a/think/providers/openai.py b/think/providers/openai.py index dd4b5a265..cd342fcaa 100644 --- a/think/providers/openai.py +++ b/think/providers/openai.py @@ -174,7 +174,7 @@ async def run_cogitate( else: prompt_text = prompt_body - # Build command — sandbox is read-only; "sol call" commands bypass + # Build command — sandbox is read-only; "sol" commands bypass # the sandbox via exec-policy rules in .codex/rules/solstone.rules # Write-enabled agents get full sandbox access sandbox = "write" if config.get("write") else "read-only" -- 2.51.2