feat(agents): add exclusive cabilities

[paul-nechifor]

Problem

Closes DIM-XXX

Solution

How to Test

Contributor License Agreement

• I have read and approved the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 73.79845% with 169 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/agents/demos/demo_capabilities.py	33.33%	128 Missing ⚠️
dimos/agents/skills/person_follow.py	8.69%	21 Missing ⚠️
dimos/agents/mcp/mcp_server.py	92.15%	3 Missing and 1 partial ⚠️
dimos/agents/mcp/tool_stream.py	84.61%	4 Missing ⚠️
dimos/agents/test_annotation.py	85.00%	3 Missing ⚠️
...er_exploration/wavefront_frontier_goal_selector.py	66.66%	3 Missing ⚠️
dimos/agents/annotation.py	85.71%	1 Missing and 1 partial ⚠️
dimos/agents/mcp/test_tool_stream.py	97.61%	2 Missing ⚠️
dimos/navigation/patrolling/module.py	50.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR introduces an exclusive-capability system for agent skills, allowing skills to declare resources they occupy (e.g., movement) so the MCP server can enforce mutual exclusion and give the LLM actionable refusal messages instead of silently overwriting ongoing actions.

• New CapabilityRegistry (capabilities.py) provides a thread-safe, per-invocation-token-scoped lock with atomic all-or-nothing multi-cap acquire, same-tool takeover semantics, and a blocking wait path for instant holders.
• @skill decorator extended with uses and lifecycle params; McpServer reads these to enforce caps before dispatch and releases them either directly (instant skills) or via the dimos/tool_stopped LCM frame emitted by ToolStream.stop() (background skills).
• Real skills updated: start_patrol, begin_exploration, and follow_person all declare uses=[CAP_MOVEMENT], lifecycle="background" and call start_tool before any early-return path so the capability is always carried by a live stream.

Confidence Score: 5/5

Safe to merge. The capability system is well-designed with comprehensive tests; the only concern is a missing exception guard in PatrollingModule._patrol_loop that is unlikely to trigger in practice.

The core CapabilityRegistry, token-scoped release, and same-tool takeover mechanism are all correct and well-tested. The one rough edge is _patrol_loop in PatrollingModule: unlike _exploration_loop and follow_person, _patrol_loop has no guard to close the tool-stream on exception. In practice the loop body only calls next_goal() and publish(), which are unlikely to throw, and the cap would be recovered by the next stop_patrol or module shutdown anyway.

dimos/navigation/patrolling/module.py — _patrol_loop has no try/finally to close the tool-stream on exception, unlike the analogous loops in the other two background skills.

Important Files Changed

Filename	Overview
dimos/agents/capabilities.py	New CapabilityRegistry — atomic all-or-nothing acquire, per-invocation token scoping for same-tool takeover, blocking acquire with can_wait predicate. Logic and thread-safety are solid.
dimos/agents/mcp/mcp_server.py	Adds capability enforcement in _handle_tools_call (blocking acquire, refusal messages with lifecycle-aware advice) and cap release via _fan_out_to_sse_queues on dimos/tool_stopped frames. Logic is correct.
dimos/agents/mcp/tool_stream.py	Adds _acquire_token capture on construction, rebind_acquire_token() for same-tool takeover, and make_stopped_notification with optional token. stop() now always emits a dimos/tool_stopped frame even when no send() occurred.
dimos/core/module.py	start_tool now does a same-tool re-stamp instead of raising on duplicate; get_skills extracts uses/lifecycle from __skill_uses__/__skill_lifecycle__. Clean and well-tested.
dimos/navigation/patrolling/module.py	start_patrol updated with uses=[CAP_MOVEMENT], lifecycle="background" and start_tool called before early-return. _stop_patrolling closes the stream. _patrol_loop has no try/finally to close the stream on exception, unlike _exploration_loop.
dimos/navigation/frontier_exploration/wavefront_frontier_goal_selector.py	begin_exploration now calls start_tool before explore(), ensuring the early-return path re-stamps the live stream and is covered by the _exploration_loop's finally block.
dimos/agents/skills/person_follow.py	follow_person updated with uses=[CAP_MOVEMENT], lifecycle="background"; uses a background_launched flag in a try/finally to close the stream on all early-return paths while leaving it open for the background thread.
dimos/agents/demos/demo_capabilities.py	New self-contained demo showing instant vs background skills, capability conflicts, and self-terminating background tools. Background loops correctly wrap body in try/finally: stop_tool.

Sequence Diagram

sequenceDiagram
    participant LLM as LLM Agent
    participant MCP as McpServer
    participant REG as CapabilityRegistry
    participant SKILL as Skill
    participant STREAM as ToolStream

    LLM->>MCP: tools/call start_patrol
    MCP->>REG: "acquire([movement], token=T1)"
    REG-->>MCP: None (success)
    MCP->>SKILL: "rpc_call(_mcp_context={acquire_token: T1})"
    SKILL->>STREAM: start_tool stamps T1
    SKILL-->>MCP: Patrol started
    Note over MCP: lifecycle=background, caps_held=False

    LLM->>MCP: tools/call turn_in_place
    MCP->>REG: "acquire([movement], token=T2)"
    REG-->>MCP: conflict (movement held by start_patrol)
    MCP-->>LLM: Cannot start turn_in_place — call stop tool first

    LLM->>MCP: tools/call stop_patrol
    MCP->>SKILL: rpc_call stop_patrol
    SKILL->>STREAM: "stop_tool emits dimos/tool_stopped token=T1"
    STREAM->>MCP: dimos/tool_stopped via LCM
    MCP->>REG: release_by_token(T1)
    MCP-->>LLM: Patrol stopped

    LLM->>MCP: tools/call turn_in_place
    MCP->>REG: "acquire([movement], token=T3)"
    REG-->>MCP: None (success)
    MCP->>SKILL: rpc_call turn_in_place
    SKILL-->>MCP: Turned 90 degrees
    Note over MCP: lifecycle=instant, release in finally
    MCP->>REG: release_by_token(T3)

Loading

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into paul/feat/capab..." | Re-trigger Greptile}