Optimize tool inventory: merge redundant tools, improve descriptions (#289)

* Optimize tool inventory: merge redundant tools, improve descriptions

Reduce agent tool count from 44 to 41 by merging and removing redundant
tools that caused LLM selection confusion:

- Merge memory_recall into memory_search: add `category` parameter for
  structured fact DB filtering, eliminating the confusion between two
  tools that both "search memory"
- Merge set_heartbeat into set_cron: add `heartbeat` boolean parameter
  to find-and-update existing heartbeat jobs
- Remove vault_status: fully redundant with vault_list
- Remove list_custom_skills: achievable with list_files

Additional improvements:
- Add wait_for_subagent skill for blocking on subagent completion
  instead of polling read_shared_state
- Clarify browser_solve_captcha description (auto-detection vs manual)
- Improve list_shared_state description (previews vs full values)
- Improve read_agent_history description (workspace logs, not history)
- Add wait_for_subagent to _UNSAFE_SKILLS (no self-waiting)
- Update all documentation and tests

* Fix lint: break long line in wait_for_subagent return

* Fix bugs and edge cases found in principal review

- Fix wait_for_subagent: check `bb is not None` instead of
  `bb.get("exists")` — read_blackboard returns raw BlackboardEntry
  dict without an "exists" field, so the success path was dead code
- Fix memory_search category path: return explicit error when category
  is set but memory_store is None, even if workspace_manager is
  available (previously fell through to workspace search, ignoring
  the caller's category filter intent)
- Fix memory_search category path: distinguish empty results (search
  worked, nothing matched) from search failure (facts is None)
- Fix set_cron: validate that message is non-empty for non-heartbeat
  cron jobs (was previously required, became optional as side effect
  of the heartbeat merge)
- Fix vault_tool.py docstring: remove "check" reference to removed
  vault_status

Tests added:
- memory_search category + no store + workspace (no fallthrough)
- memory_search category with no matching facts (empty, not error)
- set_cron heartbeat=True creates/updates (3 tests)
- set_cron regular requires non-empty message
- wait_for_subagent with no mesh_client
- wait_for_subagent with blackboard read failure
- wait_for_subagent with blackboard 404 (returns None)
- Clone registry excludes wait_for_subagent

Author: bicced

README.md

@@ -414,18 +414,17 @@ canonicalized parameters and results over a 15-call sliding window.
 | `save_artifact` | Save deliverable file and register on blackboard |
 | `update_workspace` | Update identity files (HEARTBEAT.md, USER.md) |
 | `notify_user` | Send notification to user across all connected channels |
-| `set_cron` | Schedule a recurring job |
-| `set_heartbeat` | Enable autonomous monitoring with probes |
+| `set_cron` | Schedule a recurring job (set `heartbeat=true` for autonomous wakeups) |
 | `list_cron` / `remove_cron` | Manage scheduled jobs |
 | `create_skill` | Write a new Python skill at runtime |
-| `list_custom_skills` | List all custom skills the agent has created |
 | `reload_skills` | Hot-reload all skills |
 | `spawn_agent` | Spawn an ephemeral sub-agent in a new container |
 | `spawn_subagent` | Spawn a lightweight in-container subagent for parallel subtasks |
 | `list_subagents` | List active subagents and their status |
+| `wait_for_subagent` | Wait for a subagent to complete and return its result |
 | `vault_generate_secret` | Generate and store a random secret (returns opaque handle) |
 | `vault_capture_from_page` | Capture text from browser element and store as credential |
-| `vault_list` / `vault_status` | List credential names or check if a credential exists |
+| `vault_list` | List credential names (names only, never values) |
 | `introspect` | Query own runtime state: permissions, budget, fleet, cron, health |
 | `read_agent_history` | Read another agent's conversation logs |
 

docs/agent-tools.md

@@ -45,9 +45,8 @@ All agents use a single browser architecture: **Chrome + KasmVNC**. A Chromium i
 
 | Tool | Parameters | Description |
 |------|-----------|-------------|
-| `memory_search` | `query`, `max_results` | Hybrid search across workspace files and structured DB |
+| `memory_search` | `query`, `category`, `max_results` | Hybrid search across workspace files and structured DB. Provide `category` to search only the fact database filtered to that category. |
 | `memory_save` | `content` | Save a fact to workspace daily log and structured memory |
-| `memory_recall` | `query`, `category`, `max_results` | Semantic search with optional category filtering |
 
 ### Mesh / Fleet
 
@@ -73,8 +72,7 @@ All agents use a single browser architecture: **Chrome + KasmVNC**. A Chromium i
 
 | Tool | Parameters | Description |
 |------|-----------|-------------|
-| `set_cron` | `schedule`, `message` | Schedule a recurring job (cron expression or interval) |
-| `set_heartbeat` | `schedule` | Enable autonomous monitoring (probes run automatically) |
+| `set_cron` | `schedule`, `message`, `heartbeat` | Schedule a recurring job (cron expression or interval). Set `heartbeat=true` to update your autonomous wakeup schedule. |
 | `list_cron` | -- | List scheduled jobs |
 | `remove_cron` | `job_id` | Remove a scheduled job |
 
@@ -89,7 +87,6 @@ All agents use a single browser architecture: **Chrome + KasmVNC**. A Chromium i
 | Tool | Parameters | Description |
 |------|-----------|-------------|
 | `create_skill` | `name`, `code` | Write a new Python skill at runtime |
-| `list_custom_skills` | -- | List all custom skills the agent has created |
 | `reload_skills` | -- | Hot-reload all skills from disk |
 | `spawn_agent` | `role`, `system_prompt`, `ttl` | Spawn an ephemeral sub-agent in a new container (default TTL: 3600s) |
 
@@ -103,6 +100,7 @@ Lightweight subagents that run inside the same process as the parent agent, shar
 |------|-----------|-------------|
 | `spawn_subagent` | `task`, `role`, `ttl_seconds` | Spawn a lightweight subagent for parallel subtask execution |
 | `list_subagents` | -- | List active subagents spawned by this agent and their status |
+| `wait_for_subagent` | `subagent_id`, `timeout` | Wait for a subagent to complete and return its result |
 
 ### Credential Vault
 
@@ -113,7 +111,6 @@ Agents never see credential values. All operations return opaque `$CRED{name}` h
 | `vault_generate_secret` | `name`, `length`, `charset` | Generate a random secret and store it (returns handle only) |
 | `vault_capture_from_page` | `name`, `selector` or `ref` | Read text from a browser element and store as credential |
 | `vault_list` | -- | List credential names the agent can access (names only, filtered by permissions) |
-| `vault_status` | `name` | Check if an accessible credential exists in the vault |
 
 ### System Introspection
 

docs/memory.md

@@ -170,7 +170,7 @@ Session 1: User says "My timezone is PST"
   === Chat Reset ===
 
 Session 2: User asks "What timezone am I in?"
-           Agent: memory_recall("user timezone")
+           Agent: memory_search("user timezone")
            -> Returns "PST" via semantic search
 ```
 

docs/triggering.md

@@ -114,7 +114,7 @@ Cron tick
 
 ```
 Agent: I'll monitor the system every 30 minutes.
-→ set_heartbeat(schedule="every 30m")
+→ set_cron(schedule="every 30m", heartbeat=true)
 ```
 
 The probes (disk_usage, pending_signals, pending_tasks) run automatically -- you don't need to specify them. Define your escalation rules in `HEARTBEAT.md` instead.
@@ -294,6 +294,6 @@ The watcher polls at a configurable interval, tracks file modification times, an
 | `src/host/server.py` | Webhook endpoints, cron management API |
 | `src/host/orchestrator.py` | Workflow executor (triggered by pub/sub and webhooks) |
 | `src/host/mesh.py` | PubSub system for event-driven triggering |
-| `src/agent/builtins/mesh_tool.py` | Agent-side `set_cron`, `set_heartbeat`, `list_cron`, `remove_cron` tools |
+| `src/agent/builtins/mesh_tool.py` | Agent-side `set_cron`, `list_cron`, `remove_cron` tools |
 | `src/host/watchers.py` | Polling-based file watchers for Docker volume compatibility |
 | `config/cron.json` | Persisted job state |

skills/README.md

@@ -49,9 +49,9 @@ Every agent automatically has access to built-in tools defined in
 - `read_file`, `write_file`, `list_files` — File I/O
 - `http_request` — HTTP requests
 - `browser_navigate`, `browser_screenshot`, etc. — Browser automation
-- `memory_search`, `memory_save`, `memory_recall` — Persistent memory
+- `memory_search`, `memory_save` — Persistent memory
 - `list_agents`, `spawn_agent`, `spawn_subagent`, `notify_user`, `publish_event` — Team coordination
 - `read_shared_state`, `write_shared_state`, `list_shared_state` — Shared blackboard
-- `vault_generate_secret`, `vault_capture_from_page`, `vault_list`, `vault_status` — Credential vault
+- `vault_generate_secret`, `vault_capture_from_page`, `vault_list` — Credential vault
 - `introspect` — Runtime state queries
 - `create_skill`, `reload_skills` — Self-extension

src/agent/builtins/browser_tool.py

@@ -1127,9 +1127,12 @@ async def browser_evaluate(script: str, *, mesh_client=None) -> dict:
 @skill(
     name="browser_solve_captcha",
     description=(
-        "Detect and solve a CAPTCHA on the current page. Supports reCAPTCHA "
-        "v2/v3/Enterprise, hCaptcha, and Cloudflare Turnstile. Requires a "
-        "CAPTCHA API key in the vault (2captcha_key or capsolver_key)."
+        "Manually trigger CAPTCHA detection and solving on the current page. "
+        "Usually NOT needed — browser_navigate auto-detects and solves CAPTCHAs. "
+        "Use this only when a CAPTCHA appears AFTER navigation (e.g. after clicking "
+        "a button or on a lazy-loaded challenge). Supports reCAPTCHA v2/v3/Enterprise, "
+        "hCaptcha, and Cloudflare Turnstile. Requires 2captcha_key or capsolver_key "
+        "in the vault."
     ),
     parameters={},
 )

src/agent/builtins/memory_tool.py

@@ -48,31 +48,65 @@ def _parse_fact(content: str) -> tuple[str, str]:
 @skill(
     name="memory_search",
     description=(
-        "Search your long-term memory for relevant information. "
-        "Searches both workspace files (BM25) and structured fact database (vector+BM25). "
-        "Use this when you need to recall facts, preferences, or past events."
+        "Search your long-term memory. By default searches both workspace files "
+        "and your structured fact database. Provide a category to search only "
+        "the fact database filtered to that category. Use this to recall facts, "
+        "preferences, decisions, or past events before answering questions."
     ),
     parameters={
         "query": {"type": "string", "description": "What to search for"},
+        "category": {
+            "type": "string",
+            "description": (
+                "Optional: filter to a fact category (e.g. 'user_preferences', "
+                "'decisions'). When set, searches only the structured fact database."
+            ),
+            "default": "",
+        },
         "max_results": {
             "type": "integer",
             "description": "Maximum results to return (default 5)",
             "default": 5,
         },
     },
 )
-async def memory_search(query: str, max_results: int = 5, *, workspace_manager=None, memory_store=None) -> dict:
+async def memory_search(
+    query: str, category: str = "", max_results: int = 5,
+    *, workspace_manager=None, memory_store=None,
+) -> dict:
     """Search workspace memory files and structured fact database."""
     results = []
 
-    # Workspace BM25 search
+    # Category-filtered search: only the structured fact DB
+    if category:
+        if memory_store is None:
+            return {"error": "No memory_store available for category search", "results": []}
+        # Over-fetch when filtering by category since post-fetch filtering
+        # may discard many results
+        fetch_k = max_results * 3
+        facts = await _search_with_fallback(memory_store, query, fetch_k)
+        if facts is None:
+            return {"error": "Memory search failed", "results": []}
+        for fact in facts:
+            if fact.category.lower() != category.lower():
+                continue
+            results.append({
+                "key": fact.key,
+                "value": fact.value,
+                "category": fact.category,
+                "confidence": fact.confidence,
+                "access_count": fact.access_count,
+                "source": "memory_db",
+            })
+        return {"results": results, "count": len(results)}
+
+    # Default: search both workspace and DB
     if workspace_manager is not None:
         ws_hits = workspace_manager.search(query, max_results=max_results)
         for hit in ws_hits:
             hit["source"] = "workspace"
             results.append(hit)
 
-    # Structured memory DB search (vector + BM25)
     if memory_store is not None:
         db_facts = await _search_with_fallback(memory_store, query, max_results)
         if db_facts:
@@ -96,7 +130,7 @@ async def memory_search(query: str, max_results: int = 5, *, workspace_manager=N
     description=(
         "Save an important fact or note to long-term memory. "
         "Saved to both the daily session log and the structured fact database, "
-        "so it can be recalled later with memory_recall or memory_search. "
+        "so it can be recalled later with memory_search. "
         "Examples: user preferences, decisions made, key findings."
     ),
     parameters={
@@ -116,7 +150,7 @@ async def memory_save(content: str, *, workspace_manager=None, memory_store=None
         workspace_manager.append_daily_log(content)
         saved_workspace = True
 
-    # 2. Structured memory DB (searchable via memory_recall)
+    # 2. Structured memory DB (searchable via memory_search)
     if memory_store is not None:
         try:
             # Parse content into key/value — use first sentence or clause as key
@@ -132,54 +166,3 @@ async def memory_save(content: str, *, workspace_manager=None, memory_store=None
         return {"error": "No memory backends available"}
 
     return {"saved": True, "saved_workspace": saved_workspace, "saved_db": saved_db, "content": content}
-
-
-@skill(
-    name="memory_recall",
-    description=(
-        "Search your structured fact database using semantic similarity. "
-        "Better than memory_search for recalling specific facts, preferences, and decisions. "
-        "Supports optional category filtering."
-    ),
-    parameters={
-        "query": {"type": "string", "description": "What to recall"},
-        "category": {
-            "type": "string",
-            "description": "Optional: filter by category name",
-            "default": "",
-        },
-        "max_results": {
-            "type": "integer",
-            "description": "Max results (default 5)",
-            "default": 5,
-        },
-    },
-)
-async def memory_recall(
-    query: str, category: str = "", max_results: int = 5, *, memory_store=None,
-) -> dict:
-    """Search structured fact database with optional category filter."""
-    if memory_store is None:
-        return {"error": "No memory_store available", "results": []}
-
-    # Over-fetch when filtering by category since post-fetch filtering
-    # may discard many results
-    fetch_k = max_results * 3 if category else max_results
-
-    facts = await _search_with_fallback(memory_store, query, fetch_k)
-    if facts is None:
-        return {"error": "Memory search failed", "results": []}
-
-    results = []
-    for fact in facts:
-        if category and fact.category.lower() != category.lower():
-            continue
-        results.append({
-            "key": fact.key,
-            "value": fact.value,
-            "category": fact.category,
-            "confidence": fact.confidence,
-            "access_count": fact.access_count,
-        })
-
-    return {"results": results, "count": len(results)}

src/agent/builtins/mesh_tool.py

@@ -145,10 +145,10 @@ async def write_shared_state(key: str, value: str, *, mesh_client=None) -> dict:
 @skill(
     name="list_shared_state",
     description=(
-        "List all entries on the shared blackboard matching a key prefix. "
-        "Use this to see what other agents have shared: list_shared_state(prefix='goals/') "
-        "to see all goals, or list_shared_state(prefix='context/') for shared context. "
-        "The blackboard is for agent-to-agent coordination."
+        "Discover what's on the shared blackboard by listing entries matching a key "
+        "prefix. Returns key names, authors, timestamps, and value previews — but "
+        "NOT full values (use read_shared_state for that). Use when you don't know "
+        "the exact key: prefix='tasks/' to find tasks, prefix='' to see everything."
     ),
     parameters={
         "prefix": {
@@ -362,7 +362,8 @@ async def save_artifact(
         "Schedule a recurring job for yourself. The mesh will send you the "
         "specified message on the given schedule. Use cron syntax "
         "(e.g. '0 9 * * 1-5' for weekdays at 9 AM) or natural intervals "
-        "(e.g. 'every 30m'). Returns the job ID."
+        "(e.g. 'every 30m'). Set heartbeat=true to update your autonomous "
+        "wakeup schedule instead."
     ),
     parameters={
         "schedule": {
@@ -372,57 +373,51 @@ async def save_artifact(
         "message": {
             "type": "string",
             "description": "Message the mesh will send you on each trigger",
+            "default": "",
+        },
+        "heartbeat": {
+            "type": "boolean",
+            "description": (
+                "If true, sets your autonomous heartbeat schedule (finds and "
+                "updates existing heartbeat, or creates one). Only change if "
+                "the USER explicitly asks — each heartbeat costs API credits."
+            ),
+            "default": False,
         },
     },
 )
-async def set_cron(schedule: str, message: str, *, mesh_client=None) -> dict:
+async def set_cron(
+    schedule: str, message: str = "", heartbeat: bool = False,
+    *, mesh_client=None,
+) -> dict:
     if mesh_client is None:
         return {"error": "No mesh_client available"}
     try:
+        if heartbeat:
+            # Check for existing heartbeat job and update it
+            jobs = await mesh_client.list_cron()
+            existing = next((j for j in jobs if j.get("heartbeat")), None)
+            if existing:
+                result = await mesh_client.update_cron(
+                    existing["id"], schedule=schedule,
+                )
+                return {"updated": True, "type": "heartbeat", **result}
+            # No existing heartbeat — create one
+            result = await mesh_client.create_cron(
+                schedule=schedule,
+                message=message or "heartbeat",
+                heartbeat=True,
+            )
+            return {"created": True, "type": "heartbeat", **result}
+        # Regular cron job
+        if not message:
+            return {"error": "message is required for non-heartbeat cron jobs"}
         result = await mesh_client.create_cron(schedule=schedule, message=message)
         return {"created": True, **result}
     except Exception as e:
         return {"error": f"Failed to create cron job: {e}"}
 
 
-@skill(
-    name="set_heartbeat",
-    description=(
-        "Set or update your heartbeat schedule. You are automatically given a "
-        "heartbeat on startup — only change it if the USER explicitly asks you "
-        "to. Each heartbeat costs API credits, so NEVER increase frequency on "
-        "your own. The mesh will periodically wake you to work toward your "
-        "goals and check for pending tasks. Define your autonomous rules in "
-        "HEARTBEAT.md in your workspace."
-    ),
-    parameters={
-        "schedule": {
-            "type": "string",
-            "description": "How often to wake (e.g. 'every 15m', 'every 1h', '*/30 * * * *')",
-        },
-    },
-)
-async def set_heartbeat(schedule: str, *, mesh_client=None) -> dict:
-    if mesh_client is None:
-        return {"error": "No mesh_client available"}
-    try:
-        # Check for existing heartbeat job and update it
-        jobs = await mesh_client.list_cron()
-        existing = next((j for j in jobs if j.get("heartbeat")), None)
-        if existing:
-            result = await mesh_client.update_cron(
-                existing["id"], schedule=schedule,
-            )
-            return {"updated": True, "type": "heartbeat", **result}
-        # No existing heartbeat — create one
-        result = await mesh_client.create_cron(
-            schedule=schedule, message="heartbeat", heartbeat=True,
-        )
-        return {"created": True, "type": "heartbeat", **result}
-    except Exception as e:
-        return {"error": f"Failed to set heartbeat: {e}"}
-
-
 @skill(
     name="list_cron",
     description=(
@@ -502,10 +497,10 @@ async def spawn_agent(
 @skill(
     name="read_agent_history",
     description=(
-        "Read another agent's conversation history (daily logs). Use this to "
-        "understand what another agent has been doing, what it learned, and "
-        "what context it has. Permission-checked — you can only read agents "
-        "you're allowed to message."
+        "Read another agent's workspace daily logs to understand their recent "
+        "activity — tasks worked on, tools called, and facts learned. Use this "
+        "to get context before coordinating with another agent. Permission-checked: "
+        "you can only read agents you're allowed to message."
     ),
     parameters={
         "agent_id": {