eacn3 0.3.1 → 0.3.5

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * EACN3 MCP Server — exposes 34 tools via stdio transport.
+ * EACN3 MCP Server — exposes 38 tools via stdio transport.
  *
  * All intelligence lives in Skills (host LLM). This server is just
  * state management + network API wrapper. No adapter, no registry —
@@ -12,6 +12,7 @@ import { EACN3_DEFAULT_NETWORK_ENDPOINT } from "./src/models.js";
 import * as state from "./src/state.js";
 import * as net from "./src/network-client.js";
 import * as ws from "./src/ws-manager.js";
+import * as a2a from "./src/a2a-server.js";
 // ---------------------------------------------------------------------------
 // Helper: MCP text result
 // ---------------------------------------------------------------------------
@@ -103,7 +104,7 @@ server.tool("eacn3_cluster_status", "Retrieve the full cluster topology includin
 // Server Management (4)
 // ═══════════════════════════════════════════════════════════════════════════
 // #1 eacn3_connect
-server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your FIRST call. Health-probes the endpoint, falls back to seed nodes if unreachable, registers a server, and starts a background heartbeat every 60s. Returns {server_id, network_endpoint, fallback, agents_online}. Side effects: opens WebSocket connections for any previously registered agents. Call eacn3_register_agent next.", {
+server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your FIRST call. Health-probes the endpoint, falls back to seed nodes if unreachable, registers a server, and starts a background heartbeat every 60s. Returns {server_id, network_endpoint, fallback, agents_online, restored_agents, hint}. Side effects: opens WebSocket connections for any previously registered agents. IMPORTANT: check restored_agents in the response — if you have previously registered agents, they are already reconnected and ready to use. You do NOT need to re-register them. Only call eacn3_register_agent if you need a NEW agent.", {
     network_endpoint: z.string().optional().describe(`Network URL. Defaults to ${EACN3_DEFAULT_NETWORK_ENDPOINT}`),
     seed_nodes: z.array(z.string()).optional().describe("Additional seed node URLs for fallback"),
 }, async (params) => {
@@ -120,41 +121,92 @@ server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your
         return err(`Cannot reach any network node: ${e.message}`);
     }
     s.network_endpoint = endpoint;
-    // Register as server
-    const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
-    s.server_card = {
-        server_id: res.server_id,
-        version: "0.3.0",
-        endpoint: "plugin://local",
-        owner: "plugin-user",
-        status: "online",
-    };
+    // Reuse existing server identity if available; otherwise register new
+    let sid;
+    if (s.server_card) {
+        // Try to reconnect with existing server_id via heartbeat
+        try {
+            await net.heartbeat();
+            sid = s.server_card.server_id;
+            s.server_card.status = "online";
+        }
+        catch {
+            // Server no longer known to network — re-register
+            const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
+            sid = res.server_id;
+            s.server_card = {
+                server_id: sid,
+                version: "0.3.0",
+                endpoint: "plugin://local",
+                owner: "plugin-user",
+                status: "online",
+            };
+            // Update server_id on all persisted agents and re-register them with the network
+            for (const agent of Object.values(s.agents)) {
+                agent.server_id = sid;
+                try {
+                    await net.registerAgent(agent);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    else {
+        const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
+        sid = res.server_id;
+        s.server_card = {
+            server_id: sid,
+            version: "0.3.0",
+            endpoint: "plugin://local",
+            owner: "plugin-user",
+            status: "online",
+        };
+    }
     state.save();
     // Start background heartbeat
     startHeartbeat();
-    // Reconnect WS for all existing agents
-    for (const agentId of Object.keys(s.agents)) {
-        ws.connect(agentId);
+    // Reconnect WS for all existing agents; re-register if network lost them
+    for (const agent of Object.values(s.agents)) {
+        try {
+            await net.getAgentInfo(agent.agent_id);
+        }
+        catch {
+            // Agent not found on network (e.g. server restarted with in-memory DB)
+            try {
+                await net.registerAgent(agent);
+            }
+            catch { /* best-effort */ }
+        }
+        ws.connect(agent.agent_id);
     }
+    const restoredAgents = Object.values(s.agents).map((a) => ({
+        agent_id: a.agent_id,
+        name: a.name,
+        domains: a.domains,
+        tier: a.tier,
+    }));
     return ok({
         connected: true,
-        server_id: res.server_id,
+        server_id: sid,
         network_endpoint: endpoint,
         fallback,
-        agents_online: Object.keys(s.agents).length,
+        agents_online: restoredAgents.length,
+        restored_agents: restoredAgents,
+        hint: restoredAgents.length > 0
+            ? "You have previously registered agents restored and reconnected. You can use them directly without re-registering. Call eacn3_list_my_agents() for full details."
+            : "No previous agents found. Register a new agent with eacn3_register_agent().",
     });
 });
 // #2 eacn3_disconnect
-server.tool("eacn3_disconnect", "Disconnect from the EACN3 network, unregister the server, and close all WebSocket connections. Requires: eacn3_connect first. Side effects: clears all local agent state; active tasks will timeout and hurt reputation. Returns {disconnected: true}. Only call at end of session.", {}, async () => {
+server.tool("eacn3_disconnect", "Disconnect from the EACN3 network and close all WebSocket connections. Requires: eacn3_connect first. Side effects: active tasks will timeout and hurt reputation. Server identity and agent registrations are preserved — on next eacn3_connect they will be automatically reconnected. Returns {disconnected: true}. Only call at end of session.", {}, async () => {
     stopHeartbeat();
     ws.disconnectAll();
-    try {
-        await net.unregisterServer();
-    }
-    catch { /* may already be gone */ }
+    // Do NOT call unregisterServer — it cascade-deletes all agents on the network side.
+    // We only go offline; identity is preserved for reconnection.
     const s = state.getState();
-    s.server_card = null;
-    s.agents = {};
+    if (s.server_card) {
+        s.server_card.status = "offline";
+    }
     state.save();
     return ok({ disconnected: true });
 });
@@ -204,8 +256,10 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
         max_concurrent_tasks: z.number().describe("Max tasks this Agent can handle simultaneously (0 = unlimited)"),
         concurrent: z.boolean().describe("Whether this Agent supports concurrent execution"),
     }).optional().describe("Agent capacity limits"),
-    agent_type: z.enum(["executor", "planner"]).optional().describe("Defaults to executor"),
+    tier: z.enum(["general", "expert", "expert_general", "tool"]).optional().describe("Capability tier: general (can bid on anything) > expert > expert_general > tool (only tool-level tasks). Defaults to general."),
     agent_id: z.string().optional().describe("Custom agent ID. Auto-generated if omitted."),
+    a2a_port: z.number().optional().describe("Port for A2A HTTP server. Enables direct agent-to-agent messaging. Omit to use Network relay only."),
+    a2a_url: z.string().optional().describe("Full public URL for A2A callbacks (e.g. 'http://my-server.com:3001'). Auto-generated from a2a_port if omitted."),
 }, async (params) => {
     const s = state.getState();
     if (!s.server_card)
@@ -217,15 +271,27 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
         return err("domains cannot be empty");
     const agentId = params.agent_id ?? `agent-${Date.now().toString(36)}`;
     const sid = s.server_card.server_id;
+    // Determine agent URL: real A2A endpoint or local placeholder
+    let agentUrl = `plugin://local/agents/${agentId}`;
+    if (params.a2a_port || params.a2a_url) {
+        const port = params.a2a_port ?? 0;
+        const actualPort = await a2a.startServer(port);
+        if (params.a2a_url) {
+            agentUrl = `${params.a2a_url.replace(/\/$/, "")}/agents/${agentId}`;
+        }
+        else {
+            agentUrl = `http://localhost:${actualPort}/agents/${agentId}`;
+        }
+    }
     // Assemble AgentCard (what adapter used to do)
     const card = {
         agent_id: agentId,
         name: params.name,
-        agent_type: params.agent_type ?? "executor",
+        tier: params.tier ?? "general",
         domains: params.domains,
         skills: params.skills ?? [],
         capabilities: params.capabilities,
-        url: `plugin://local/agents/${agentId}`,
+        url: agentUrl,
         server_id: sid,
         network_id: "",
         description: params.description,
@@ -241,10 +307,12 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
         agent_id: agentId,
         seeds: res.seeds,
         domains: params.domains,
+        url: agentUrl,
+        a2a_server: a2a.isRunning() ? { port: a2a.getServerPort() } : null,
     });
 });
 // #6 eacn3_get_agent
-server.tool("eacn3_get_agent", "Fetch the full AgentCard for any agent by ID — checks local state first, then queries the network. Returns {agent_id, name, agent_type, domains, skills, capabilities, url, server_id, description}. No side effects. Use to inspect an agent before sending messages or evaluating bids.", {
+server.tool("eacn3_get_agent", "Fetch the full AgentCard for any agent by ID — checks local state first, then queries the network. Returns {agent_id, name, domains, skills, capabilities, url, server_id, description}. No side effects. Use to inspect an agent before sending messages or evaluating bids.", {
     agent_id: z.string(),
 }, async (params) => {
     // Check local first
@@ -293,17 +361,20 @@ server.tool("eacn3_unregister_agent", "Remove an agent from the network and clos
     const res = await net.unregisterAgent(params.agent_id);
     ws.disconnect(params.agent_id);
     state.removeAgent(params.agent_id);
+    // Stop A2A server if no agents remain
+    if (state.listAgents().length === 0 && a2a.isRunning()) {
+        await a2a.stopServer();
+    }
     return ok({ unregistered: true, agent_id: params.agent_id, ...res });
 });
 // #9 eacn3_list_my_agents
-server.tool("eacn3_list_my_agents", "List all agents registered on this local server instance. Returns {count, agents[]} where each agent includes agent_id, name, agent_type, domains, and ws_connected (WebSocket status). No network call — reads local state only. Use to check which agents are active and receiving events.", {}, async () => {
+server.tool("eacn3_list_my_agents", "List all agents registered on this local server instance. Returns {count, agents[]} where each agent includes agent_id, name, domains, tier, and ws_connected (WebSocket status). No network call — reads local state only. Use to check which agents are active and receiving events.", {}, async () => {
     const agents = state.listAgents();
     return ok({
         count: agents.length,
         agents: agents.map((a) => ({
             agent_id: a.agent_id,
             name: a.name,
-            agent_type: a.agent_type,
             domains: a.domains,
             ws_connected: ws.isConnected(a.agent_id),
         })),
@@ -386,6 +457,8 @@ server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for ot
         contact_id: z.string().optional().describe("Human contact identifier"),
         timeout_s: z.number().optional().describe("Seconds to wait for human response before auto-reject"),
     }).optional().describe("Human-in-the-loop contact settings"),
+    level: z.enum(["general", "expert", "expert_general", "tool"]).optional().describe("Task complexity level. Determines which agent tiers can bid. 'tool' = only tool-level tasks for simple tool wrappers. Defaults to 'general' (open to all)."),
+    invited_agent_ids: z.array(z.string()).optional().describe("Agent IDs to directly approve — these agents bypass bid admission filtering (confidence×reputation threshold). Use to pre-select specific agents you trust."),
     initiator_id: z.string().optional().describe("Agent ID of the task initiator (auto-injected if omitted)"),
 }, async (params) => {
     const initiatorId = resolveAgentId(params.initiator_id);
@@ -409,6 +482,8 @@ server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for ot
         max_concurrent_bidders: params.max_concurrent_bidders,
         max_depth: params.max_depth,
         human_contact: params.human_contact,
+        level: params.level ?? "general",
+        invited_agent_ids: params.invited_agent_ids,
     });
     // Track locally
     state.updateTask({
@@ -485,17 +560,79 @@ server.tool("eacn3_confirm_budget", "Approve or reject a bid that exceeded your
     const res = await net.confirmBudget(params.task_id, initiatorId, params.approved, params.new_budget);
     return ok(res);
 });
+// #22b eacn3_invite_agent
+server.tool("eacn3_invite_agent", "Invite a specific agent to bid on your task, bypassing the normal bid admission filter (confidence×reputation threshold). The invited agent still needs to actively bid — this just guarantees their bid won't be rejected by the admission algorithm. Use when you know a specific agent is right for the job but they might not pass the automated filter (e.g. new agent with low reputation). Also sends a direct_message notification to the invited agent. Requires: you must be the task initiator.", {
+    task_id: z.string(),
+    agent_id: z.string().describe("Agent ID to invite"),
+    message: z.string().optional().describe("Optional message to send with the invitation"),
+    initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
+}, async (params) => {
+    const initiatorId = resolveAgentId(params.initiator_id);
+    const res = await net.inviteAgent(params.task_id, initiatorId, params.agent_id);
+    // Send a direct_message notification to the invited agent
+    const inviteContent = params.message
+        ? `[Task Invitation] You've been invited to bid on task ${params.task_id}. Your bid will bypass admission filtering. Message from initiator: ${params.message}`
+        : `[Task Invitation] You've been invited to bid on task ${params.task_id}. Your bid will bypass admission filtering.`;
+    // Record outgoing message in session
+    state.addMessage(initiatorId, {
+        from: initiatorId,
+        to: params.agent_id,
+        content: inviteContent,
+        timestamp: Date.now(),
+        direction: "out",
+    });
+    // Try to notify the invited agent
+    try {
+        const agentCard = await net.getAgentInfo(params.agent_id);
+        if (agentCard.url && !agentCard.url.startsWith("plugin://")) {
+            const eventsUrl = agentCard.url.replace(/\/$/, "") + "/events";
+            await fetch(eventsUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    type: "direct_message",
+                    from: initiatorId,
+                    content: inviteContent,
+                    task_id: params.task_id,
+                    invitation: true,
+                }),
+            }).catch(() => { });
+        }
+        else {
+            // Relay via network
+            await net.relayMessage({
+                to: {
+                    network_id: agentCard.network_id ?? "",
+                    server_id: agentCard.server_id,
+                    agent_id: params.agent_id,
+                },
+                from: {
+                    network_id: state.getState().server_card?.server_id ?? "",
+                    server_id: state.getServerId() ?? "",
+                    agent_id: initiatorId,
+                },
+                content: inviteContent,
+            }).catch(() => { });
+        }
+    }
+    catch {
+        // Agent lookup failed — invitation still recorded server-side
+    }
+    return ok(res);
+});
 // ═══════════════════════════════════════════════════════════════════════════
 // Task Operations — Executor (5)
 // ═══════════════════════════════════════════════════════════════════════════
 // #23 eacn3_submit_bid
-server.tool("eacn3_submit_bid", "Bid on an open task by specifying your confidence (0.0-1.0 honest ability estimate) and price in credits. Server evaluates: confidence * reputation must meet threshold or bid is rejected. Returns {status} which is one of: 'executing' (start work now), 'waiting_execution' (queued, slots full), 'rejected' (threshold not met), or 'pending_confirmation' (price > budget, awaiting initiator approval). Side effects: if accepted, tracks task locally as executor role. If price > budget, initiator gets a 'budget_confirmation' event.", {
+server.tool("eacn3_submit_bid", "Bid on an open task by specifying your confidence (0.0-1.0 honest ability estimate) and price in credits. Server evaluates: confidence * reputation must meet threshold or bid is rejected (unless you are in the task's invited_agent_ids list — invited agents bypass admission). Also checks tier/level compatibility: tool-tier agents can only bid on tool-level tasks. Returns {status} which is one of: 'executing' (start work now), 'waiting_execution' (queued, slots full), 'rejected' (threshold not met or tier mismatch), or 'pending_confirmation' (price > budget, awaiting initiator approval). Side effects: if accepted, tracks task locally as executor role.", {
     task_id: z.string(),
     confidence: z.number().min(0).max(1).describe("0.0-1.0 confidence in ability to complete"),
     price: z.number().describe("Bid price"),
     agent_id: z.string().optional().describe("Bidder agent ID (auto-injected if omitted)"),
 }, async (params) => {
     const agentId = resolveAgentId(params.agent_id);
+    // Tier/level filtering and invite bypass are handled server-side in matcher.check_bid().
+    // No client-side pre-flight — the network returns "rejected" with reason for tier mismatches.
     const res = await net.submitBid(params.task_id, agentId, params.confidence, params.price);
     // Track locally if not rejected (status could be "executing", "waiting_execution", etc.)
     if (res.status && res.status !== "rejected") {
@@ -549,10 +686,11 @@ server.tool("eacn3_create_subtask", "Delegate part of your work by creating a ch
     domains: z.array(z.string()),
     budget: z.number(),
     deadline: z.string().optional(),
+    level: z.enum(["general", "expert", "expert_general", "tool"]).optional().describe("Task level for the subtask. If omitted, inherits from parent task."),
     initiator_id: z.string().optional().describe("Agent ID of the executor creating the subtask (auto-injected if omitted)"),
 }, async (params) => {
     const initiatorId = resolveAgentId(params.initiator_id);
-    const task = await net.createSubtask(params.parent_task_id, initiatorId, { description: params.description }, params.domains, params.budget, params.deadline);
+    const task = await net.createSubtask(params.parent_task_id, initiatorId, { description: params.description }, params.domains, params.budget, params.deadline, params.level);
     return ok({
         subtask_id: task.id,
         parent_task_id: params.parent_task_id,
@@ -561,27 +699,34 @@ server.tool("eacn3_create_subtask", "Delegate part of your work by creating a ch
     });
 });
 // #27 eacn3_send_message
-// A2A direct — agent.md:358-362: peer-to-peer, bypasses Network
-server.tool("eacn3_send_message", "Send a direct agent-to-agent message bypassing the task system. Local agents receive it instantly in their event buffer; remote agents receive it via HTTP POST to their /events endpoint. Returns {sent, to, from, local}. The recipient sees a 'direct_message' event with payload.from and payload.content. Will fail if the remote agent has no reachable URL or is offline.", {
+// A2A direct + Network relay fallback — agent.md:358-362
+server.tool("eacn3_send_message", "Send a direct agent-to-agent message. Delivery order: (1) local agent → instant push, (2) remote agent with reachable URL → A2A direct POST, (3) fallback → Network relay via WebSocket. Returns {sent, to, from, method} where method is 'local', 'a2a_direct', or 'relay'. All sent messages are stored in your session history. The recipient sees a 'direct_message' event. Use /eacn3-message to handle received messages.", {
     agent_id: z.string().describe("Target agent ID"),
     content: z.string(),
     sender_id: z.string().optional().describe("Your agent ID (auto-injected if omitted)"),
 }, async (params) => {
     const senderId = params.sender_id ?? resolveAgentId();
     const targetId = params.agent_id;
-    const message = {
-        type: "direct_message",
-        task_id: "",
-        payload: { from: senderId, content: params.content },
-        received_at: Date.now(),
-    };
-    // Local agent — direct push to event buffer
+    // Record outgoing message in session
+    state.addMessage(senderId, {
+        from: senderId,
+        to: targetId,
+        content: params.content,
+        timestamp: Date.now(),
+        direction: "out",
+    });
+    // 1. Local agent — direct push to event buffer
     const localAgent = state.getAgent(targetId);
     if (localAgent) {
-        state.pushEvents([message]);
-        return ok({ sent: true, to: targetId, from: senderId, local: true });
+        state.pushEvents([{
+                type: "direct_message",
+                task_id: "",
+                payload: { from: senderId, content: params.content },
+                received_at: Date.now(),
+            }]);
+        return ok({ sent: true, to: targetId, from: senderId, method: "local" });
     }
-    // Remote agent — POST to their URL callback (A2A direct, agent.md:160-168)
+    // 2. Remote agent — look up AgentCard
     let agentCard;
     try {
         agentCard = await net.getAgentInfo(targetId);
@@ -589,28 +734,47 @@ server.tool("eacn3_send_message", "Send a direct agent-to-agent message bypassin
     catch {
         return err(`Agent ${targetId} not found`);
     }
-    if (!agentCard.url || agentCard.url.startsWith("plugin://")) {
-        return err(`Agent ${targetId} has no reachable URL: ${agentCard.url}`);
+    // 3. Try A2A direct if agent has a real HTTP URL
+    if (agentCard.url && !agentCard.url.startsWith("plugin://")) {
+        const eventsUrl = agentCard.url.replace(/\/$/, "") + "/events";
+        try {
+            const res = await fetch(eventsUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    type: "direct_message",
+                    from: senderId,
+                    content: params.content,
+                }),
+            });
+            if (res.ok) {
+                return ok({ sent: true, to: targetId, from: senderId, method: "a2a_direct" });
+            }
+            // Direct failed — fall through to relay
+        }
+        catch {
+            // Direct failed — fall through to relay
+        }
     }
-    // POST /events on agent's URL (agent.md:164)
-    const eventsUrl = agentCard.url.replace(/\/$/, "") + "/events";
+    // 4. Network relay fallback — route via Network node using three-layer addressing
     try {
-        const res = await fetch(eventsUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                type: "direct_message",
-                from: senderId,
-                content: params.content,
-            }),
+        await net.relayMessage({
+            to: {
+                network_id: agentCard.network_id ?? "",
+                server_id: agentCard.server_id,
+                agent_id: targetId,
+            },
+            from: {
+                network_id: state.getState().server_card?.server_id ?? "",
+                server_id: state.getServerId() ?? "",
+                agent_id: senderId,
+            },
+            content: params.content,
         });
-        if (!res.ok) {
-            return err(`POST ${eventsUrl} failed: ${res.status}`);
-        }
-        return ok({ sent: true, to: targetId, from: senderId, local: false });
+        return ok({ sent: true, to: targetId, from: senderId, method: "relay" });
     }
     catch (e) {
-        return err(`Failed to reach agent at ${eventsUrl}: ${e.message}`);
+        return err(`All delivery methods failed for ${targetId}: ${e.message}`);
     }
 });
 // ═══════════════════════════════════════════════════════════════════════════
@@ -654,7 +818,27 @@ server.tool("eacn3_deposit", "Add EACN credits to an agent's available balance.
 // ═══════════════════════════════════════════════════════════════════════════
 // Events (1)
 // ═══════════════════════════════════════════════════════════════════════════
-// #32 eacn3_get_events
+// Messaging (2)
+// ═══════════════════════════════════════════════════════════════════════════
+// #32 eacn3_get_messages
+server.tool("eacn3_get_messages", "Get the message history between your agent and another agent. Returns {count, messages[]} with each message containing {from, to, content, timestamp, direction}. direction is 'in' (received) or 'out' (sent). Messages are stored per-session, capped at 100 per peer. Use to review conversation context before replying via eacn3_send_message.", {
+    agent_id: z.string().optional().describe("Your agent ID (auto-injected if only one registered)"),
+    peer_agent_id: z.string().describe("The other agent's ID"),
+}, async (params) => {
+    const agentId = params.agent_id ?? resolveAgentId();
+    const messages = state.getMessages(agentId, params.peer_agent_id);
+    return ok({ count: messages.length, messages });
+});
+// #33 eacn3_list_sessions
+server.tool("eacn3_list_sessions", "List all agents you have active message sessions with. Returns {count, peers[]} where each peer is an agent_id. Use to discover ongoing conversations. Check individual sessions with eacn3_get_messages.", {
+    agent_id: z.string().optional().describe("Your agent ID (auto-injected if only one registered)"),
+}, async (params) => {
+    const agentId = params.agent_id ?? resolveAgentId();
+    const peers = state.listSessions(agentId);
+    return ok({ count: peers.length, peers });
+});
+// ═══════════════════════════════════════════════════════════════════════════
+// #34 eacn3_get_events
 server.tool("eacn3_get_events", "Drain the in-memory event buffer, returning all pending events and clearing them. Returns {count, events[]} where event types include: task_broadcast, discussions_updated, subtask_completed, awaiting_retrieval, budget_confirmation, timeout, direct_message. Call periodically in your main loop. Events arrive via WebSocket and accumulate until drained — missing events means missed tasks and messages.", {}, async () => {
     const events = state.drainEvents();
     return ok({
@@ -707,6 +891,22 @@ function registerEventCallbacks() {
                 // New task available — auto-evaluate bid if agent has matching domains
                 autoBidEvaluate(agentId, event).catch(() => { });
                 break;
+            case "direct_message": {
+                // Another agent sent a direct message — store in session
+                const payload = event.payload;
+                const from = payload?.from;
+                const content = payload?.content;
+                if (from && content !== undefined) {
+                    state.addMessage(agentId, {
+                        from,
+                        to: agentId,
+                        content: typeof content === "string" ? content : JSON.stringify(content),
+                        timestamp: Date.now(),
+                        direction: "in",
+                    });
+                }
+                break;
+            }
         }
     });
 }