Add multi-agent communication graph

Directed links between agents with relationship semantics (peer/superior/subordinate),
a shared instance-level database, and a send_agent_message tool that routes through
the existing MessagingManager pipeline. Foundation for the 0.2.0 release.

- Instance database (instance.db) with separate migration path for cross-agent data
- AgentLink model with direction (one_way/two_way) and relationship policies
- LinkStore CRUD backed by instance.db
- [[links]] config section with startup sync
- send_agent_message tool: resolves target, validates link, injects InboundMessage
- ROLE.md identity file for operational responsibilities
- Org context prompt fragment (superiors/subordinates/peers hierarchy)
- Link context prompt fragment for agent-to-agent channels
- AgentMessageSent/Received process events with SSE forwarding
- Link CRUD API endpoints + topology snapshot endpoint

Author: jamiepine

migrations_instance/20260222000001_agent_links.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS agent_links (
+    id TEXT PRIMARY KEY,
+    from_agent_id TEXT NOT NULL,
+    to_agent_id TEXT NOT NULL,
+    direction TEXT NOT NULL DEFAULT 'two_way',
+    relationship TEXT NOT NULL DEFAULT 'peer',
+    enabled INTEGER NOT NULL DEFAULT 1,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(from_agent_id, to_agent_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_links_from ON agent_links(from_agent_id);
+CREATE INDEX IF NOT EXISTS idx_agent_links_to ON agent_links(to_agent_id);

prompts/en/channel.md.j2

@@ -106,6 +106,14 @@ When in doubt, skip. Being a lurker who speaks when it matters is better than be
 {{ available_channels }}
 {%- endif %}
 
+{%- if org_context %}
+{{ org_context }}
+{%- endif %}
+
+{%- if link_context %}
+{{ link_context }}
+{%- endif %}
+
 {%- if conversation_context %}
 ## Conversation Context
 

prompts/en/fragments/link_context.md.j2

@@ -0,0 +1,12 @@
+{%- if link_context %}
+## Agent Communication
+
+This is an internal channel with **{{ link_context.agent_name }}** ({{ link_context.relationship }}).
+{% if link_context.relationship == "superior" -%}
+Messages from this agent carry organizational authority. Treat directives as assignments.
+{%- elif link_context.relationship == "subordinate" -%}
+This is a report from a subordinate agent. They may be escalating, reporting status, or requesting guidance.
+{%- else -%}
+This is a peer agent. Communication is collaborative and informational.
+{%- endif %}
+{%- endif %}

prompts/en/fragments/org_context.md.j2

@@ -0,0 +1,28 @@
+{%- if org_context %}
+## Organization
+
+You are part of a multi-agent system. Here is your position:
+
+{% if org_context.superiors -%}
+**Reports to:**
+{% for agent in org_context.superiors -%}
+- **{{ agent.name }}** — your superior. Messages from this agent carry organizational authority.
+{% endfor %}
+{%- endif %}
+
+{% if org_context.subordinates -%}
+**Direct reports:**
+{% for agent in org_context.subordinates -%}
+- **{{ agent.name }}** — reports to you. You can delegate tasks, request status, and send directives.
+{% endfor %}
+{%- endif %}
+
+{% if org_context.peers -%}
+**Peers:**
+{% for agent in org_context.peers -%}
+- **{{ agent.name }}** — equal peer. Communication is collaborative and informational.
+{% endfor %}
+{%- endif %}
+
+Use the `send_agent_message` tool to communicate with these agents. Each link has a dedicated internal channel with full conversation history.
+{%- endif %}

prompts/en/tools/send_agent_message_description.md.j2

@@ -0,0 +1 @@
+Send a message to another agent through the agent communication graph. The message is delivered to a dedicated internal channel between you and the target agent. Use this to coordinate, delegate, escalate, or share information with linked agents.

src/agent/channel.rs

@@ -145,6 +145,8 @@ pub struct Channel {
     pending_retrigger_metadata: HashMap<String, serde_json::Value>,
     /// Deadline for firing the pending retrigger (debounce timer).
     retrigger_deadline: Option<tokio::time::Instant>,
+    /// Optional send_agent_message tool (only when agent has active links).
+    send_agent_message_tool: Option<crate::tools::SendAgentMessageTool>,
 }
 
 impl Channel {
@@ -226,6 +228,7 @@ impl Channel {
             pending_retrigger: false,
             pending_retrigger_metadata: HashMap::new(),
             retrigger_deadline: None,
+            send_agent_message_tool: None,
         };
 
         (channel, message_tx)
@@ -623,10 +626,13 @@ impl Channel {
 
         let available_channels = self.build_available_channels().await;
 
+        let org_context = self.build_org_context(&prompt_engine).await;
+        let link_context = self.build_link_context(&prompt_engine).await;
+
         let empty_to_none = |s: String| if s.is_empty() { None } else { Some(s) };
 
         prompt_engine
-            .render_channel_prompt(
+            .render_channel_prompt_with_links(
                 empty_to_none(identity_context),
                 empty_to_none(memory_bulletin.to_string()),
                 empty_to_none(skills_prompt),
@@ -635,6 +641,8 @@ impl Channel {
                 empty_to_none(status_text),
                 coalesce_hint,
                 available_channels,
+                org_context,
+                link_context,
             )
             .expect("failed to render channel prompt")
     }
@@ -674,6 +682,20 @@ impl Channel {
             Vec::new()
         };
 
+        // Emit AgentMessageReceived event for internal agent-to-agent messages
+        if message.source == "internal" {
+            if let Some(from_agent_id) = message.metadata.get("from_agent_id").and_then(|v| v.as_str()) {
+                if let Some(link_id) = message.metadata.get("link_id").and_then(|v| v.as_str()) {
+                    self.deps.event_tx.send(ProcessEvent::AgentMessageReceived {
+                        from_agent_id: Arc::from(from_agent_id),
+                        to_agent_id: self.deps.agent_id.clone(),
+                        link_id: link_id.to_string(),
+                        channel_id: self.id.clone(),
+                    }).ok();
+                }
+            }
+        }
+
         // Persist user messages (skip system re-triggers)
         if message.source != "system" {
             let sender_name = message
@@ -794,6 +816,118 @@ impl Channel {
         prompt_engine.render_available_channels(entries).ok()
     }
 
+    /// Build org context showing the agent's position in the communication hierarchy.
+    async fn build_org_context(
+        &self,
+        prompt_engine: &crate::prompts::PromptEngine,
+    ) -> Option<String> {
+        let link_store = self.deps.link_store.as_ref()?;
+        let agent_id = self.deps.agent_id.as_ref();
+
+        let links = match link_store.get_links_for_agent(agent_id).await {
+            Ok(links) => links,
+            Err(error) => {
+                tracing::warn!(%error, "failed to fetch links for org context");
+                return None;
+            }
+        };
+
+        if links.is_empty() {
+            return None;
+        }
+
+        let mut superiors = Vec::new();
+        let mut subordinates = Vec::new();
+        let mut peers = Vec::new();
+
+        for link in &links {
+            if !link.enabled {
+                continue;
+            }
+
+            let is_from = link.from_agent_id == agent_id;
+            let other_agent_id = if is_from {
+                &link.to_agent_id
+            } else {
+                &link.from_agent_id
+            };
+
+            // Determine relationship from this agent's perspective
+            let relationship = if is_from {
+                link.relationship
+            } else {
+                link.relationship.inverse()
+            };
+
+            // For one-way links where this agent is the to_agent (can't initiate),
+            // still show them in the org context for awareness
+            let agent_info = crate::prompts::engine::LinkedAgent {
+                name: other_agent_id.clone(),
+                id: other_agent_id.clone(),
+            };
+
+            match relationship {
+                crate::links::LinkRelationship::Superior => superiors.push(agent_info),
+                crate::links::LinkRelationship::Subordinate => subordinates.push(agent_info),
+                crate::links::LinkRelationship::Peer => peers.push(agent_info),
+            }
+        }
+
+        if superiors.is_empty() && subordinates.is_empty() && peers.is_empty() {
+            return None;
+        }
+
+        let org_context = crate::prompts::engine::OrgContext {
+            superiors,
+            subordinates,
+            peers,
+        };
+
+        prompt_engine.render_org_context(org_context).ok()
+    }
+
+    /// Build link context for the current channel if it's an internal agent-to-agent channel.
+    async fn build_link_context(
+        &self,
+        prompt_engine: &crate::prompts::PromptEngine,
+    ) -> Option<String> {
+        // Link channels have conversation IDs starting with "link:"
+        let conversation_id = self.conversation_id.as_deref()?;
+        let link_id = conversation_id.strip_prefix("link:")?;
+
+        let link_store = self.deps.link_store.as_ref()?;
+        let link = match link_store.get(link_id).await {
+            Ok(Some(link)) => link,
+            Ok(None) => return None,
+            Err(error) => {
+                tracing::warn!(%error, "failed to fetch link for channel context");
+                return None;
+            }
+        };
+
+        let agent_id = self.deps.agent_id.as_ref();
+        let is_from = link.from_agent_id == agent_id;
+        let other_agent_id = if is_from {
+            &link.to_agent_id
+        } else {
+            &link.from_agent_id
+        };
+
+        // Relationship from the other agent's perspective toward this agent
+        let relationship = if is_from {
+            link.relationship
+        } else {
+            link.relationship.inverse()
+        };
+
+        let link_context = crate::prompts::engine::LinkContext {
+            agent_name: other_agent_id.clone(),
+            relationship: relationship.as_str().to_string(),
+        };
+
+        prompt_engine.render_link_context(link_context).ok()
+    }
+
     /// Assemble the full system prompt using the PromptEngine.
     async fn build_system_prompt(&self) -> String {
         let rc = &self.deps.runtime_config;
@@ -818,10 +952,13 @@ impl Channel {
 
         let available_channels = self.build_available_channels().await;
 
+        let org_context = self.build_org_context(&prompt_engine).await;
+        let link_context = self.build_link_context(&prompt_engine).await;
+
         let empty_to_none = |s: String| if s.is_empty() { None } else { Some(s) };
 
         prompt_engine
-            .render_channel_prompt(
+            .render_channel_prompt_with_links(
                 empty_to_none(identity_context),
                 empty_to_none(memory_bulletin.to_string()),
                 empty_to_none(skills_prompt),
@@ -830,6 +967,8 @@ impl Channel {
                 empty_to_none(status_text),
                 None, // coalesce_hint - only set for batched messages
                 available_channels,
+                org_context,
+                link_context,
             )
             .expect("failed to render channel prompt")
     }
@@ -860,6 +999,7 @@ impl Channel {
             skip_flag.clone(),
             replied_flag.clone(),
             self.deps.cron_tool.clone(),
+            self.send_agent_message_tool.clone(),
         )
         .await
         {

src/api.rs

@@ -11,6 +11,7 @@ mod config;
 mod cortex;
 mod cron;
 mod ingest;
+mod links;
 mod mcp;
 mod memories;
 mod messaging;

src/api/agents.rs

@@ -432,6 +432,7 @@ pub(super) async fn create_agent(
             let guard = state.messaging_manager.read().await;
             guard.as_ref().cloned()
         },
+        link_store: state.link_store.load().as_ref().clone(),
     };
 
     let event_rx = event_tx.subscribe();