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 skill-level mutual exclusion: skills declare @skill(uses=["movement"]) and the MCP server consults a CapabilityRegistry before each tools/call, either waiting (for instant skills) or refusing with a human-readable message (for background skills). The end-to-end token lifecycle — MCP server acquires, ToolStream stamps the stop frame, _fan_out_to_sse_queues releases — is well designed, with same-tool takeover handled cleanly via rebind_acquire_token.

• CapabilityRegistry: thread-safe all-or-nothing multi-cap acquire with per-invocation token scoping; stale takeover tokens no longer leak the hold.
• start_tool changed from raising on duplicate to re-stamping the token, enabling background skills to call it unconditionally before any early-return path.
• PatrollingModule, WavefrontFrontierExplorer, PersonFollowSkillContainer, and NavigationSkillContainer updated to declare CAP_MOVEMENT; a hardware-free demo and thorough unit tests accompany the change.
• humancli.py gains live per-tool streaming boxes with tool-result anchoring via direct mutation of Textual private internals (_line_cache).

Confidence Score: 5/5

Safe to merge; the capability system is well-structured with no correctness gaps in the core acquisition/release path.

The token-scoped registry, same-tool takeover, and always-emitting stop frame work correctly together. All early-return paths in the updated skills call stop_tool or rely on the re-stamp mechanism. The only fragility is the direct use of Textual's private _line_cache in the UI layer, which is cosmetic and isolated.

dimos/utils/cli/human/humancli.py — the _insert_after method couples to Textual private internals.

Important Files Changed

Filename	Overview
dimos/agents/capabilities.py	New CapabilityRegistry: thread-safe all-or-nothing acquire with per-invocation token scoping and same-tool takeover; design is solid.
dimos/agents/annotation.py	Refactored skill decorator to support uses and lifecycle params, with lifecycle validation before the bare-form check; correct and well-typed.
dimos/agents/mcp/mcp_server.py	Integrates CapabilityRegistry into tool dispatch: acquires before call, releases on failure or delegates to tool-stream for background skills; exception path correctly releases caps via finally block.
dimos/agents/mcp/tool_stream.py	Always emits dimos/tool_stopped on close (spinning up a transport if needed), adds rebind_acquire_token() for same-tool takeover; stop is idempotent.
dimos/core/module.py	Changed start_tool from raising on duplicate to re-stamping the acquire token on the live stream, enabling same-tool takeover semantics; old error message removed correctly.
dimos/utils/cli/human/humancli.py	Adds live per-tool streaming boxes and tool-result anchoring; _insert_after directly accesses RichLog._line_cache (private Textual attribute) and mutates log.lines/log.virtual_size, coupling tightly to internal Textual state.
dimos/agents/skills/person_follow.py	Moves start_tool to the parent skill before early returns so all code paths release capability; removes now-redundant patrol auto-stop (handled by capability system).
dimos/navigation/patrolling/module.py	Adds @skill(uses=[CAP_MOVEMENT], lifecycle="background"), calls start_tool before early-return and stop_tool in _stop_patrolling; double-stop on both explicit and main() teardown paths remains safe (idempotent pop).
dimos/navigation/frontier_exploration/wavefront_frontier_goal_selector.py	Extracts _run_exploration_loop so _exploration_loop can wrap it with a finally: stop_tool that releases movement on every exit path, including self-termination.

Sequence Diagram

sequenceDiagram
    participant LLM as LLM / McpClient
    participant MCP as McpServer
    participant REG as CapabilityRegistry
    participant SKILL as Skill (background)
    participant STREAM as ToolStream
    participant SSE as _fan_out_to_sse_queues

    LLM->>MCP: "tools/call {name, args}"
    MCP->>REG: acquire(caps, tool_name, token, timeout)
    alt cap free or same-tool takeover
        REG-->>MCP: None (success)
        MCP->>SKILL: "rpc_call(_mcp_context={acquire_token})"
        SKILL->>STREAM: start_tool(name) stamps token
        SKILL-->>MCP: "Patrol started."
        Note over MCP: caps_held=False (background) cap stays with ToolStream
        MCP-->>LLM: result text
        loop background work
            SKILL->>STREAM: tool_update(name, msg)
            STREAM->>SSE: notifications/message
        end
        SKILL->>STREAM: stop_tool(name)
        STREAM->>SSE: "dimos/tool_stopped {token}"
        SSE->>REG: release_by_token(token)
        REG-->>SSE: ["movement"] released
    else cap held by different tool
        REG-->>MCP: (cap, holder_tool)
        MCP-->>LLM: "Cannot start X: capability Y is held by Z. Call stop tool first."
    end

Loading

_{Reviews (3): Last reviewed commit: "feat(agents): add exclusive cabilities" | Re-trigger Greptile}