Feature: connect 2 agents through bluetooth

[finettt]

Just find it funny)

[finettt]

@claude, create a draft of architecture for it

[claude]

Claude finished @finettt's task in 4m 26s —— View job

---

Bluetooth Agent Connection - Architecture Draft

I've analyzed the DroidClaw codebase and created an architectural draft for connecting two agents through Bluetooth. This design enables peer-to-peer communication between Android devices running DroidClaw.

---

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Bluetooth Agent Layer                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│  BluetoothManager (Service)                                                     │
│  ├── BluetoothServer (accepts connections)                                      │
│  ├── BluetoothClient (initiates connections)                                    │
│  └── ConnectionPool (manages active connections)                                │
│                                                                                  │
│  AgentConnection (per-connection session)                                       │
│  ├── MessageQueue (incoming/outgoing)                                           │
│  ├── ProtocolHandler (serialization/deserialization)                           │
│  └── ToolProxy (forwards tool calls to remote agent)                           │
│                                                                                  │
│  BluetoothToolRegistry                                                          │
│  ├── send_file                                                                  │
│  ├── receive_file                                                               │
│  ├── execute_remote_shell                                                       │
│  └── list_connected_agents                                                      │
└─────────────────────────────────────────────────────────────────────────────────┘

---

Core Components

1. BluetoothManager

Location: app/src/main/java/io/finett/droidclaw/bluetooth/BluetoothManager.java

Manages Bluetooth adapter, discovery, and connection lifecycle.

public class BluetoothManager {
    // Service mode - acts as server
    public void startServer() {...}
    
    // Client mode - connects to peer
    public void connect(String deviceAddress) {...}
    
    // Connection management
    public List<BluetoothDevice> getConnectedDevices() {...}
    public void disconnect(String deviceAddress) {...}
    
    // Callback interface for connection events
    public interface Callback {
        void onConnectionEstablished(String deviceName, String address);
        void onConnectionLost(String address);
        void onMessageReceived(String address, AgentMessage message);
        void onError(String error);
    }
}

Permissions required:

• BLUETOOTH_CONNECT (Android 12+)
• BLUETOOTH_SCAN (Android 12+)
• BLUETOOTH (deprecated but still needed for older versions)

---

2. AgentConnection

Location: app/src/main/java/io/finett/droidclaw/bluetooth/AgentConnection.java

Represents a bidirectional session with a connected agent.

public class AgentConnection {
    private final BluetoothDevice device;
    private final InputStream inputStream;
    private final OutputStream outputStream;
    private final MessageHandler handler;
    
    // Send message to remote agent
    public void sendMessage(AgentMessage message) {...}
    
    // Forward tool call to remote agent
    public ToolResult executeRemoteTool(String toolName, JsonObject arguments) {...}
    
    // Get connection metadata
    public String getDeviceName() {...}
    public String getAddress() {...}
    public long getConnectedAt() {...}
}

---

3. Protocol Layer

Location: app/src/main/java/io/finett/droidclaw/bluetooth/protocol/

Handles serialization/deserialization of messages.

// Message types
public enum MessageType {
    TOOL_CALL,
    TOOL_RESULT,
    TEXT_RESPONSE,
    FILE_TRANSFER,
    PING,
    PONG
}

// Agent message structure
public class AgentMessage {
    private String id;              // Unique message ID
    private MessageType type;
    private String fromAgent;       // Agent identifier
    private long timestamp;
    private JsonObject payload;     // Type-specific data
}

Serialization: Uses Gson for JSON payloads, with optional compression for large file transfers.

---

4. Bluetooth Tools

Location: app/src/main/java/io/finett/droidclaw/tool/impl/Bluetooth*.java

New tools for the ToolRegistry:

Tool Name	Description	Requires Approval
send_file	Send a file to connected agent	Yes (file access)
receive_file	Receive a file from connected agent	Yes (file write)
execute_remote_shell	Execute shell command on remote agent	Yes (remote shell)
list_connected_agents	List all connected Bluetooth agents	No
agent_chat	Send chat message to connected agent	No

Example tool definition:

public class BluetoothSendFileTool implements Tool {
    private static final String TOOL_NAME = "send_file";
    
    public ToolDefinition getDefinition() {
        return new ToolDefinition(
            TOOL_NAME,
            "Send a file to a connected Bluetooth agent",
            new ParametersBuilder()
                .addString("device_address", "Bluetooth MAC address", true)
                .addString("file_path", "Path to file in workspace", true)
                .addString("target_name", "Name for file on remote device", false)
                .build()
        );
    }
}

---

Integration Points

AgentLoop Integration

The AgentLoop can now delegate tool execution to remote agents:

// In AgentLoop.handleToolCalls()
if (toolName.startsWith("agent_")) {
    // Route to remote agent via Bluetooth
    AgentConnection connection = bluetoothManager.getConnection(targetAgent);
    ToolResult result = connection.executeRemoteTool(toolName, arguments);
    // Return result as if it was local
}

Settings Integration

Add Bluetooth settings to AgentConfig:

{
  "bluetooth": {
    "enabled": true,
    "discoverable": false,
    "autoConnect": ["AA:BB:CC:DD:EE:FF"],
    "maxConnections": 2
  }
}

---

Security Considerations

1. Authentication: Use Bluetooth pairing with PIN verification
2. Encryption: Enable Bluetooth LE encryption where available
3. Access Control: Validate all file paths through PathValidator
4. Approval: All destructive operations require user approval
5. Rate Limiting: Prevent message flooding attacks

---

Android API Notes

• Min SDK 22: Bluetooth API is stable but requires runtime permissions
• Android 12+ (API 31+): New permission model requires BLUETOOTH_CONNECT and BLUETOOTH_SCAN
• Discovery: Bluetooth Classic discovery is power-intensive; use Bluetooth LE for low-power scanning

---

Next Steps (Implementation Tasks)

• Create BluetoothManager service
• Implement AgentConnection class
• Design protocol serialization format
• Create Bluetooth tool implementations
• Add settings UI for Bluetooth configuration
• Handle connection lifecycle (discover, pair, connect)
• Implement file transfer protocol
• Add approval UI for remote tool execution

---

Alternative Approach: Mesh Networking

For future expansion, consider building on top of Nearby Connections API (Google Play Services):

• Automatic device discovery
• Cross-platform (Android/iOS)
• Better handling of network changes
• Higher throughput

This would require:

implementation "com.google.android.gms:play-services-nearby:18.5.0"

---

Let me know if you'd like me to proceed with implementing any specific component of this architecture!

[finettt]

@claude, make agent can decide to chat with nearby agent on its own. Also user can restrict agent to be accessible from other agents. Add new file relationships.md (at same level as soul.md and user.md).

[claude]

Claude finished @finettt's task in 12m 11s —— View job • claude/issue-45-20260412-1625 • [Create PR ➔](https://github.com/finettt/DroidClaw/compare/main...claude/issue-45-20260412-1625?quick_pull=1&title=Issue%20%2345%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%2345%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

I've completed the implementation of agent relationships and accessibility settings. Here's what was done:

---

Implementation Summary

1. Created relationships.md Identity File

Location: app/src/main/assets/identity/relationships.md

This new identity file provides the agent with context about:

• Agent-to-agent connections: How to discover and connect with nearby agents via Bluetooth
• Autonomous decision-making: Guidelines for when to initiate connections with other agents
• User accessibility control: How user settings restrict agent accessibility
• Connection best practices: Verification, rate limiting, and error handling

2. Updated Identity Management

Files: IdentityManager.java, WorkspaceManager.java

• IdentityManager now loads relationships.md as a third system message (after soul.md and user.md)
• WorkspaceManager creates relationships.md from assets during workspace initialization
• IdentityContext class extended to include relationships content

3. Added Agent Accessibility Settings

Files: AgentConfig.java, SettingsManager.java

Three new settings control agent accessibility:

Setting	Default	Description
agentAccessibilityEnabled	true	Can other agents connect to this agent?
agentAutoConnect	true	Can this agent initiate connections to nearby agents?
agentDiscoverable	false	Is this agent visible during Bluetooth discovery?

4. Settings Persistence

The new settings are persisted in the existing JSON settings structure under the agents/defaults key:

{
  "agents": {
    "defaults": {
      "model": "...",
      "shellAccess": false,
      "agentAccessibilityEnabled": true,
      "agentAutoConnect": true,
      "agentDiscoverable": false,
      ...
    }
  }
}

---

How It Works

1. Agent Identity: The agent now knows it's DroidClaw and can connect with other DroidClaw agents via Bluetooth

2. User Control: Users can restrict agent accessibility through settings:

   • Disable agentAccessibilityEnabled to reject all incoming connections
   • Disable agentAutoConnect to prevent the agent from initiating connections
   • Enable agentDiscoverable to make the agent visible during Bluetooth discovery

3. Autonomous Decision: The agent can decide to chat with nearby agents based on:

   • Task complexity requiring additional capabilities
   • Need for computational resources
   • Knowledge gaps that another agent might fill
   • User settings allowing autonomous connections

---

Next Steps for Full Bluetooth Implementation

This PR adds the foundation for agent-to-agent communication. To complete the Bluetooth feature, the following would need to be implemented:

• BluetoothManager service for connection management
• AgentConnection class for bidirectional sessions
• Protocol layer for message serialization
• Bluetooth tools (send_file, execute_remote_shell, etc.)
• Settings UI for Bluetooth configuration

---

| Branch: claude/issue-45-20260412-1625