eacn3 0.3.5 → 0.5.0

package/dist/server.js

@@ -11,13 +11,24 @@ import { z } from "zod";
 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 ws from "./src/event-transport.js";
 import * as a2a from "./src/a2a-server.js";
+import * as rc from "./src/reverse-control.js";
 // ---------------------------------------------------------------------------
 // Helper: MCP text result
 // ---------------------------------------------------------------------------
 function ok(data) {
-    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    const result = {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+    };
+    // Fallback directive injection: when sampling is unavailable,
+    // append pending event directives to any tool response so the
+    // Host LLM sees actionable events without explicit polling.
+    const directives = rc.drainDirectives();
+    if (directives) {
+        result.content.push({ type: "text", text: directives });
+    }
+    return result;
 }
 function err(message) {
     return { content: [{ type: "text", text: JSON.stringify({ error: message }) }] };
@@ -70,7 +81,7 @@ function stopHeartbeat() {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new McpServer({ name: "eacn3", version: "0.3.0" });
+const server = new McpServer({ name: "eacn3", version: "0.5.0" });
 // ═══════════════════════════════════════════════════════════════════════════
 // Health / Cluster (2)
 // ═══════════════════════════════════════════════════════════════════════════
@@ -104,7 +115,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, 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.", {
+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: starts event polling 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) => {
@@ -132,11 +143,11 @@ server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your
         }
         catch {
             // Server no longer known to network — re-register
-            const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
+            const res = await net.registerServer("0.5.0", "plugin://local", "plugin-user");
             sid = res.server_id;
             s.server_card = {
                 server_id: sid,
-                version: "0.3.0",
+                version: "0.5.0",
                 endpoint: "plugin://local",
                 owner: "plugin-user",
                 status: "online",
@@ -152,11 +163,11 @@ server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your
         }
     }
     else {
-        const res = await net.registerServer("0.3.0", "plugin://local", "plugin-user");
+        const res = await net.registerServer("0.5.0", "plugin://local", "plugin-user");
         sid = res.server_id;
         s.server_card = {
             server_id: sid,
-            version: "0.3.0",
+            version: "0.5.0",
             endpoint: "plugin://local",
             owner: "plugin-user",
             status: "online",
@@ -195,10 +206,28 @@ server.tool("eacn3_connect", "Connect to the EACN3 network — this must be your
         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().",
+        toolkit: {
+            workflow: {
+                eacn3_next: "Periodic dispatch loop — call on a regular interval to process pending events one at a time. Returns the highest-priority event with action directives. This is the ONLY tool that spans the full task lifecycle.",
+                eacn3_get_events: "Drain all pending events at once (bulk alternative to next).",
+            },
+            team: {
+                eacn3_team_setup: "Form a team of agents around a shared git repo. Creates handshake tasks between all pairs.",
+                eacn3_team_status: "Check team formation progress — which handshakes are done, which peer branches are known.",
+                eacn3_team_set_branch: "Record your git branch name for a team after creating it.",
+            },
+            task: {
+                eacn3_create_task: "Publish a task (supports team_id to auto-inject team preamble).",
+                eacn3_create_subtask: "Delegate part of your work as a child task.",
+                eacn3_submit_bid: "Bid on a task you want to execute.",
+                eacn3_submit_result: "Submit your completed work.",
+                eacn3_select_result: "Pick the winning result (triggers payment).",
+            },
+        },
     });
 });
 // #2 eacn3_disconnect
-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 () => {
+server.tool("eacn3_disconnect", "Disconnect from the EACN3 network and stop event polling. 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();
     // Do NOT call unregisterServer — it cascade-deletes all agents on the network side.
@@ -241,7 +270,7 @@ server.tool("eacn3_server_info", "Get current server connection state, including
 // ═══════════════════════════════════════════════════════════════════════════
 // #5 eacn3_register_agent
 // Inlines: adapter (AgentCard assembly) + registry (validate + persist + DHT)
-server.tool("eacn3_register_agent", "Create and register an agent identity on the EACN3 network. Requires: eacn3_connect first. Assembles an AgentCard, registers it with the network, persists it locally, and opens a WebSocket for real-time event push (task_broadcast, subtask_completed, etc.). Returns {agent_id, seeds, domains}. Domains control which task broadcasts you receive — be specific (e.g. 'python-coding' not 'coding').", {
+server.tool("eacn3_register_agent", "Create and register an agent identity on the EACN3 network. Requires: eacn3_connect first. Assembles an AgentCard, registers it with the network, persists it locally, and starts polling for push events (task_broadcast, subtask_completed, etc.). Returns {agent_id, seeds, domains}. Domains control which task broadcasts you receive — be specific (e.g. 'python-coding' not 'coding').", {
     name: z.string().describe("Agent display name"),
     description: z.string().describe("What this Agent does"),
     domains: z.array(z.string()).describe("Capability domains (e.g. ['translation', 'coding'])"),
@@ -260,6 +289,11 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
     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."),
+    reverse_control: z.object({
+        enabled: z.boolean().optional().describe("Enable MCP reverse control (sampling/notifications). Default true."),
+        sampling_events: z.array(z.string()).optional().describe("Event types that trigger LLM sampling (e.g. ['task_broadcast', 'direct_message']). Default: all actionable events."),
+        notification_events: z.array(z.string()).optional().describe("Event types that send notifications only (e.g. ['task_collected', 'task_timeout']). Default: status events."),
+    }).optional().describe("Configure MCP reverse control — lets the network proactively drive your agent via sampling requests."),
 }, async (params) => {
     const s = state.getState();
     if (!s.server_card)
@@ -300,8 +334,21 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
     const res = await net.registerAgent(card);
     // Persist locally
     state.addAgent(card);
-    // Open WebSocket for event push
+    // Start polling for push events
     ws.connect(agentId);
+    // Configure reverse control for this agent
+    if (params.reverse_control?.enabled !== false) {
+        const rcPolicies = {};
+        const samplingEvents = params.reverse_control?.sampling_events ?? ["task_broadcast", "direct_message", "subtask_completed", "bid_request_confirmation", "discussion_update"];
+        const notifEvents = params.reverse_control?.notification_events ?? ["task_collected"];
+        for (const e of samplingEvents)
+            rcPolicies[e] = { method: "sampling" };
+        for (const e of notifEvents)
+            rcPolicies[e] = { method: "notification" };
+        rcPolicies["task_timeout"] = { method: "auto_action", autoAction: "report_and_close" };
+        rc.configure(agentId, { enabled: true, policies: rcPolicies });
+    }
+    const rcStatus = rc.getStatus();
     return ok({
         registered: true,
         agent_id: agentId,
@@ -309,6 +356,29 @@ server.tool("eacn3_register_agent", "Create and register an agent identity on th
         domains: params.domains,
         url: agentUrl,
         a2a_server: a2a.isRunning() ? { port: a2a.getServerPort() } : null,
+        reverse_control: {
+            enabled: params.reverse_control?.enabled !== false,
+            sampling_available: rcStatus.samplingAvailable,
+            fallback: rcStatus.samplingAvailable ? "none" : "directive_injection",
+        },
+        toolkit: {
+            workflow: {
+                eacn3_next: "Periodic dispatch loop — call on a regular interval to process pending events one at a time. Returns the highest-priority event with action directives. This is the ONLY tool that spans the full task lifecycle.",
+                eacn3_get_events: "Drain all pending events at once (bulk alternative to next).",
+            },
+            team: {
+                eacn3_team_setup: "Form a team of agents around a shared git repo. Creates handshake tasks between all pairs.",
+                eacn3_team_status: "Check team formation progress — which handshakes are done, which peer branches are known.",
+                eacn3_team_set_branch: "Record your git branch name for a team after creating it.",
+            },
+            task: {
+                eacn3_create_task: "Publish a task (supports team_id to auto-inject team preamble).",
+                eacn3_create_subtask: "Delegate part of your work as a child task.",
+                eacn3_submit_bid: "Bid on a task you want to execute.",
+                eacn3_submit_result: "Submit your completed work.",
+                eacn3_select_result: "Pick the winning result (triggers payment).",
+            },
+        },
     });
 });
 // #6 eacn3_get_agent
@@ -355,11 +425,12 @@ server.tool("eacn3_update_agent", "Update a registered agent's mutable fields: n
     return ok({ updated: true, agent_id, ...res });
 });
 // #8 eacn3_unregister_agent
-server.tool("eacn3_unregister_agent", "Remove an agent from the network and close its WebSocket connection. Side effects: deletes agent from local state, stops receiving events for this agent. Active tasks assigned to this agent will timeout and hurt reputation. Returns {unregistered: true, agent_id}.", {
+server.tool("eacn3_unregister_agent", "Remove an agent from the network and stop its event polling. Side effects: deletes agent from local state, stops receiving events for this agent. Active tasks assigned to this agent will timeout and hurt reputation. Returns {unregistered: true, agent_id}.", {
     agent_id: z.string(),
 }, async (params) => {
     const res = await net.unregisterAgent(params.agent_id);
     ws.disconnect(params.agent_id);
+    rc.unconfigure(params.agent_id);
     state.removeAgent(params.agent_id);
     // Stop A2A server if no agents remain
     if (state.listAgents().length === 0 && a2a.isRunning()) {
@@ -368,7 +439,7 @@ server.tool("eacn3_unregister_agent", "Remove an agent from the network and clos
     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, 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 () => {
+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 polling_active (event polling 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,
@@ -376,7 +447,8 @@ server.tool("eacn3_list_my_agents", "List all agents registered on this local se
             agent_id: a.agent_id,
             name: a.name,
             domains: a.domains,
-            ws_connected: ws.isConnected(a.agent_id),
+            connected: ws.isConnected(a.agent_id),
+            transport: ws.getTransportStatus(a.agent_id),
         })),
     });
 });
@@ -444,6 +516,7 @@ server.tool("eacn3_list_tasks", "Browse all tasks on the network with optional f
 server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for other agents to bid on. Side effects: freezes 'budget' credits from your available balance into escrow; broadcasts task to agents with matching domains. Returns {task_id, status, budget, local_matches[]}. Requires: sufficient balance (use eacn3_deposit first if needed). Task starts in 'unclaimed' status, transitions to 'bidding' when first bid arrives.", {
     description: z.string(),
     budget: z.number(),
+    team_id: z.string().optional().describe("Team ID to attach team collaboration preamble. Required when the initiator belongs to multiple ready teams. If omitted and the initiator is in exactly one ready team, that team is used automatically."),
     domains: z.array(z.string()).optional(),
     deadline: z.string().optional().describe("ISO 8601 deadline"),
     max_concurrent_bidders: z.number().optional(),
@@ -469,11 +542,48 @@ server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for ot
         ? localAgents.filter((a) => a.agent_id !== initiatorId &&
             params.domains.some((d) => a.domains.includes(d)))
         : [];
+    // Auto-inject team collaboration preamble if initiator is in a ready team
+    let finalDescription = params.description;
+    const teams = state.getTeamsForAgent(initiatorId);
+    const readyTeams = teams.filter((t) => t.status === "ready");
+    let activeTeam;
+    if (params.team_id) {
+        activeTeam = readyTeams.find((t) => t.team_id === params.team_id);
+        if (!activeTeam) {
+            return err(`Team ${params.team_id} not found or not ready. Available ready teams: ${readyTeams.map((t) => t.team_id).join(", ") || "(none)"}`);
+        }
+    }
+    else if (readyTeams.length === 1) {
+        activeTeam = readyTeams[0];
+    }
+    else if (readyTeams.length > 1) {
+        return err(`Initiator belongs to multiple ready teams: ${readyTeams.map((t) => t.team_id).join(", ")}. Please specify team_id.`);
+    }
+    if (activeTeam) {
+        const branchInfo = Object.entries(activeTeam.peer_branches)
+            .map(([id, branch]) => `  - ${id}: ${branch}`)
+            .join("\n");
+        const preamble = [
+            `[TEAM COLLABORATION — ${activeTeam.team_id}]`,
+            `Git repo: ${activeTeam.git_repo}`,
+            `Team members: ${activeTeam.agent_ids.join(", ")}`,
+            branchInfo ? `Branches:\n${branchInfo}` : "",
+            "",
+            "Team rules:",
+            "- We are collaborating as a team on a shared git repo. Coordinate via branches and messages.",
+            "- If any part of this task would be done better by a teammate, create a subtask (budget=0) with invited_agent_ids targeting that teammate.",
+            "- Before submitting your result, pull and check teammates' branches for relevant changes.",
+            "- Communicate progress and blockers via eacn3_send_message to your teammates.",
+            "",
+            "[USER TASK]",
+        ].filter(Boolean).join("\n");
+        finalDescription = `${preamble}\n${params.description}`;
+    }
     const task = await net.createTask({
         task_id: taskId,
         initiator_id: initiatorId,
         content: {
-            description: params.description,
+            description: finalDescription,
             expected_output: params.expected_output,
         },
         domains: params.domains,
@@ -488,6 +598,7 @@ server.tool("eacn3_create_task", "Publish a new task to the EACN3 network for ot
     // Track locally
     state.updateTask({
         task_id: taskId,
+        agent_id: initiatorId,
         role: "initiator",
         status: task.status,
         domains: params.domains ?? [],
@@ -518,6 +629,25 @@ server.tool("eacn3_select_result", "Pick the winning result for a task, triggeri
 }, async (params) => {
     const initiatorId = resolveAgentId(params.initiator_id);
     const res = await net.selectResult(params.task_id, initiatorId, params.agent_id);
+    // If this was a team handshake task, extract peer branch and update local team state
+    const teams = state.getTeamsForAgent(initiatorId);
+    for (const team of teams) {
+        const handshakeTarget = Object.entries(team.handshake_out).find(([, taskId]) => taskId === params.task_id);
+        if (handshakeTarget) {
+            // Fetch the result to get the branch name
+            try {
+                const taskData = await net.getTask(params.task_id);
+                const results = taskData?.results ?? [];
+                const winnerResult = results.find((r) => r.agent_id === params.agent_id);
+                const branch = winnerResult?.content?.branch;
+                if (branch) {
+                    state.updateTeamPeerBranch(team.team_id, handshakeTarget[0], branch);
+                }
+            }
+            catch { /* best effort */ }
+            break;
+        }
+    }
     return ok(res);
 });
 // #19 eacn3_close_task
@@ -540,7 +670,7 @@ server.tool("eacn3_update_deadline", "Extend or shorten a task's deadline. Requi
     return ok(res);
 });
 // #21 eacn3_update_discussions
-server.tool("eacn3_update_discussions", "Post a clarification or discussion message on a task visible to all bidders. Requires: you must be the task initiator. Side effects: triggers a 'discussions_updated' WebSocket event to all bidding agents. Returns confirmation. Use to provide additional context or answer bidder questions.", {
+server.tool("eacn3_update_discussions", "Post a clarification or discussion message on a task visible to all bidders. Requires: you must be the task initiator. Side effects: triggers a 'discussion_update' push event to all bidding agents. Returns confirmation. Use to provide additional context or answer bidder questions.", {
     task_id: z.string(),
     message: z.string(),
     initiator_id: z.string().optional().describe("Initiator agent ID (auto-injected if omitted)"),
@@ -550,7 +680,7 @@ server.tool("eacn3_update_discussions", "Post a clarification or discussion mess
     return ok(res);
 });
 // #22 eacn3_confirm_budget
-server.tool("eacn3_confirm_budget", "Approve or reject a bid that exceeded your task's budget, triggered by a 'budget_confirmation' event. Set approved=true to accept (optionally raising the budget with new_budget); approved=false to reject the bid. Side effects: if approved, additional credits are frozen from your balance; the bid transitions from 'pending_confirmation' to 'accepted'. Returns updated task status.", {
+server.tool("eacn3_confirm_budget", "Approve or reject a bid that exceeded your task's budget, triggered by a 'bid_request_confirmation' event. Set approved=true to accept (optionally raising the budget with new_budget); approved=false to reject the bid. Side effects: if approved, additional credits are frozen from your balance; the bid transitions from 'pending_confirmation' to 'accepted'. Returns updated task status.", {
     task_id: z.string(),
     approved: z.boolean(),
     new_budget: z.number().optional(),
@@ -638,6 +768,7 @@ server.tool("eacn3_submit_bid", "Bid on an open task by specifying your confiden
     if (res.status && res.status !== "rejected") {
         state.updateTask({
             task_id: params.task_id,
+            agent_id: agentId,
             role: "executor",
             status: "bidding",
             domains: [],
@@ -700,7 +831,7 @@ server.tool("eacn3_create_subtask", "Delegate part of your work by creating a ch
 });
 // #27 eacn3_send_message
 // 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.", {
+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. 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)"),
@@ -718,7 +849,8 @@ server.tool("eacn3_send_message", "Send a direct agent-to-agent message. Deliver
     // 1. Local agent — direct push to event buffer
     const localAgent = state.getAgent(targetId);
     if (localAgent) {
-        state.pushEvents([{
+        state.pushEvents(targetId, [{
+                msg_id: crypto.randomUUID().replace(/-/g, ""),
                 type: "direct_message",
                 task_id: "",
                 payload: { from: senderId, content: params.content },
@@ -839,24 +971,431 @@ server.tool("eacn3_list_sessions", "List all agents you have active message sess
 });
 // ═══════════════════════════════════════════════════════════════════════════
 // #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();
+server.tool("eacn3_get_events", "Drain the in-memory event buffer for a specific agent, returning its pending events and clearing them. Returns {count, events[], reverse_control} where event types include: task_broadcast, bid_request_confirmation, bid_result, discussion_update, subtask_completed, task_collected, task_timeout, adjudication_task, direct_message. With reverse_control enabled, high-priority events may already have been handled via LLM sampling — check reverse_control.status for details. Call periodically in your main loop.", {
+    agent_id: z.string().optional().describe("Agent ID to drain events for (auto-injected if omitted)"),
+}, async (params) => {
+    const agentId = resolveAgentId(params.agent_id);
+    const events = state.drainEvents(agentId);
     return ok({
         count: events.length,
         events,
+        reverse_control: rc.getStatus(),
+    });
+});
+// #39 eacn3_await_events — long-polling reverse control
+server.tool("eacn3_await_events", "Block until a network event arrives or timeout expires, then return with the event AND a suggested action. This is the reverse-control mechanism when MCP sampling is unavailable (e.g. OpenClaw). Instead of polling eacn3_get_events in a loop, call this — it waits for the network to push something, then tells you exactly what to do. Returns {event, suggested_action, suggested_tool, suggested_params, urgency} per event, or {timeout: true}. Prefer this over eacn3_get_events for reactive agent loops.", {
+    agent_id: z.string().optional().describe("Agent ID to await events for (auto-injected if omitted)"),
+    timeout_seconds: z.number().optional().describe("Max seconds to wait (1-120). Default 30."),
+    event_types: z.array(z.string()).optional().describe("Only return for these event types. Default: all."),
+}, async (params) => {
+    const agentId = resolveAgentId(params.agent_id);
+    const timeoutSec = Math.min(Math.max(params.timeout_seconds ?? 30, 1), 120);
+    const filterTypes = params.event_types;
+    // Check immediate buffered events
+    const immediate = drainMatchingEvents(agentId, filterTypes);
+    if (immediate.length > 0) {
+        return ok(buildAwaitResponse(immediate));
+    }
+    // Long-poll
+    const result = await new Promise((resolve) => {
+        const deadline = setTimeout(() => { cleanup(); resolve([]); }, timeoutSec * 1000);
+        const poll = setInterval(() => {
+            const events = drainMatchingEvents(agentId, filterTypes);
+            if (events.length > 0) {
+                cleanup();
+                resolve(events);
+            }
+        }, 500);
+        function cleanup() { clearTimeout(deadline); clearInterval(poll); }
+    });
+    if (result.length === 0) {
+        return ok({ timeout: true, waited_seconds: timeoutSec, hint: "No events arrived. Call again to keep waiting, or proceed with other work." });
+    }
+    return ok(buildAwaitResponse(result));
+});
+// #41 eacn3_next — single-event non-blocking poll
+const URGENCY_ORDER = {
+    task_broadcast: 1,
+    direct_message: 1,
+    subtask_completed: 1,
+    bid_request_confirmation: 1,
+    result_submitted: 1,
+    task_collected: 2,
+    bid_result: 2,
+    discussion_update: 3,
+    task_timeout: 4,
+    adjudication_task: 2,
+};
+function buildNextAction(event) {
+    const payload = event.payload;
+    switch (event.type) {
+        case "task_broadcast": {
+            // Detect team handshake tasks
+            const desc = String(payload?.description ?? "");
+            if (desc.startsWith("Team handshake:") || payload?.budget === 0) {
+                // Check if this looks like a handshake (0-budget, team-coordination domain)
+                const domains = payload.domains ?? [];
+                if (domains.includes("team-coordination")) {
+                    return {
+                        action: "handshake",
+                        description: `Team handshake from another agent on task ${event.task_id}. ` +
+                            `Bid with price=0 confidence=1, then submit_result with your branch name: ` +
+                            `{branch: "agent/your-id", _handshake_ack: true, team_id: "..."}.`,
+                        tool: "eacn3_submit_bid",
+                        params: { task_id: event.task_id, confidence: 1, price: 0 },
+                    };
+                }
+            }
+            return {
+                action: "bid",
+                description: `New task [${(payload.domains ?? []).join(", ")}] budget=${payload.budget ?? "?"}. Evaluate and bid.`,
+                tool: "eacn3_submit_bid",
+                params: { task_id: event.task_id },
+            };
+        }
+        case "direct_message":
+            return {
+                action: "reply",
+                description: `Message from ${payload.from ?? "?"}: "${String(payload.content ?? "").slice(0, 200)}"`,
+                tool: "eacn3_send_message",
+                params: { to_agent_id: payload.from, task_id: event.task_id },
+            };
+        case "subtask_completed":
+            return {
+                action: "collect",
+                description: `Subtask ${payload.subtask_id ?? "?"} completed. Fetch results and continue.`,
+                tool: "eacn3_get_task_results",
+                params: { task_id: String(payload.subtask_id ?? event.task_id) },
+            };
+        case "bid_request_confirmation":
+            return {
+                action: "confirm",
+                description: `Bid on ${event.task_id} exceeded budget. Approve or reject.`,
+                tool: "eacn3_confirm_budget",
+                params: { task_id: event.task_id },
+            };
+        case "result_submitted":
+            return {
+                action: "review",
+                description: `Agent ${payload.agent_id ?? "?"} submitted a result for task ${event.task_id} (${payload.results_count ?? "?"}/${payload.executing_count ?? "?"} results in). Call eacn3_get_task_results to retrieve, then eacn3_select_result to accept${payload.all_submitted ? " — all executors have submitted" : ""}.`,
+                tool: "eacn3_get_task_results",
+                params: { task_id: event.task_id },
+            };
+        case "task_collected":
+            return {
+                action: "collect",
+                description: `Task ${event.task_id}: all executors have submitted. Retrieve and select.`,
+                tool: "eacn3_get_task_results",
+                params: { task_id: event.task_id },
+            };
+        case "bid_result": {
+            const accepted = payload?.accepted;
+            if (accepted) {
+                return {
+                    action: "execute",
+                    description: `Bid accepted on ${event.task_id}. Start working.`,
+                    tool: "eacn3_get_task",
+                    params: { task_id: event.task_id },
+                };
+            }
+            return {
+                action: "note",
+                description: `Bid rejected on ${event.task_id}. Reason: ${payload?.reason ?? "unknown"}.`,
+                tool: null,
+                params: {},
+            };
+        }
+        case "task_timeout":
+            return {
+                action: "note",
+                description: `Task ${event.task_id} timed out.`,
+                tool: null,
+                params: {},
+            };
+        default:
+            return {
+                action: "check",
+                description: `Event "${event.type}" on ${event.task_id}.`,
+                tool: "eacn3_get_task",
+                params: { task_id: event.task_id },
+            };
+    }
+}
+server.tool("eacn3_next", "Non-blocking single-step work dispatcher: returns the ONE highest-priority pending event for this agent with a clear action directive. When you get a task back, process it, then call eacn3_next again. When idle is returned, there are no NEW network events — but check the returned 'prompts' array for context-aware guidance: unfinished tasks, delegated work to review, reflection questions, and delegation suggestions. Act on those prompts instead of waiting. Never sleep or poll — always keep making progress.", {
+    agent_id: z.string().optional().describe("Agent ID (auto-injected if omitted)"),
+}, async (params) => {
+    const agentId = resolveAgentId(params.agent_id);
+    const events = state.drainEvents(agentId);
+    if (events.length === 0) {
+        // Build context-aware prompts based on agent's current task state
+        const tasks = Object.values(state.getState().local_tasks).filter((t) => t.agent_id === agentId);
+        const inProgress = tasks.filter((t) => t.role === "executor" && (t.status === "bidding" || t.status === "unclaimed"));
+        const delegated = tasks.filter((t) => t.role === "initiator" && t.status !== "completed" && t.status !== "no_one");
+        const completed = tasks.filter((t) => t.status === "completed" || t.status === "awaiting_retrieval");
+        const prompts = [];
+        if (inProgress.length > 0) {
+            prompts.push(`You have ${inProgress.length} task(s) still in progress (${inProgress.map(t => t.task_id).join(", ")}). Have you actually finished them? Are the results thorough and correct?`);
+        }
+        if (delegated.length > 0) {
+            prompts.push(`You delegated ${delegated.length} task(s) to other agents (${delegated.map(t => t.task_id).join(", ")}). Have you checked their results? Do the results meet your expectations?`);
+        }
+        if (completed.length > 0) {
+            prompts.push(`You have ${completed.length} completed task(s). Have you reviewed all the results? Have you reflected on the overall outcome based on everything you've gathered so far?`);
+        }
+        // Check message sessions — any conversations with recent incoming messages?
+        const sessions = state.listSessions(agentId);
+        const unanswered = [];
+        for (const peerId of sessions) {
+            const msgs = state.getMessages(agentId, peerId);
+            if (msgs.length > 0 && msgs[msgs.length - 1].direction === "in") {
+                unanswered.push(peerId);
+            }
+        }
+        if (unanswered.length > 0) {
+            prompts.push(`You have unanswered messages from ${unanswered.length} agent(s) (${unanswered.join(", ")}). Have you replied? Is there information they need from you?`);
+        }
+        if (sessions.length > 0 && unanswered.length === 0) {
+            prompts.push(`You have ${sessions.length} active conversation(s). Are you waiting for replies? Should you follow up?`);
+        }
+        if (inProgress.length === 0 && delegated.length === 0 && completed.length === 0 && sessions.length === 0) {
+            prompts.push("No active tasks or conversations. Continue with your current work.");
+        }
+        // Always-applicable reflective prompts
+        prompts.push("Are there parts of your current work that another agent with different expertise could handle better? Consider delegating via eacn3_create_task.", "If you're stuck on something, have you considered alternative approaches?", "If you have long-running subtasks, have you broken them into smaller pieces that can run in parallel?");
+        return ok({
+            idle: true,
+            active_tasks: inProgress.map(t => t.task_id),
+            delegated_tasks: delegated.map(t => t.task_id),
+            completed_tasks: completed.map(t => t.task_id),
+            active_conversations: sessions.length,
+            unanswered_from: unanswered,
+            prompts,
+        });
+    }
+    // Sort by urgency (lower number = higher priority)
+    events.sort((a, b) => (URGENCY_ORDER[a.type] ?? 5) - (URGENCY_ORDER[b.type] ?? 5));
+    // Take the first (highest priority), put the rest back
+    const [top, ...rest] = events;
+    if (rest.length > 0)
+        state.pushEvents(agentId, rest);
+    const next = buildNextAction(top);
+    return ok({
+        idle: false,
+        remaining: rest.length,
+        event: top,
+        ...next,
+    });
+});
+// #42 eacn3_team_setup — human-facing team coordination toolkit
+server.tool("eacn3_team_setup", "Human-facing toolkit: form a team of agents around a shared git repo. " +
+    "Creates 0-budget handshake tasks between every pair of agents (both directions). " +
+    "Each agent creates its own operation branch and learns peers' branches through handshake responses. " +
+    "Set peers_running_next=true if other agents already have next loops — this agent will notify them via messages first.", {
+    agent_ids: z.array(z.string()).min(2).describe("Agent IDs to form a team"),
+    git_repo: z.string().describe("Git repo URL for recording operations"),
+    peers_running_next: z.boolean().optional().describe("If true, notify peers via messages before handshakes"),
+}, async (params) => {
+    const localAgents = state.listAgents();
+    const localIds = new Set(localAgents.map((a) => a.agent_id));
+    // Find which of the requested agents are local
+    const myAgents = params.agent_ids.filter((id) => localIds.has(id));
+    if (myAgents.length === 0) {
+        return err("None of the specified agent_ids are registered on this server");
+    }
+    const teamId = `team-${Date.now().toString(36)}`;
+    const results = [];
+    for (const myId of myAgents) {
+        const peers = params.agent_ids.filter((id) => id !== myId);
+        // Save team info
+        const teamInfo = {
+            team_id: teamId,
+            git_repo: params.git_repo,
+            agent_ids: params.agent_ids,
+            my_agent_id: myId,
+            peer_branches: {},
+            handshake_out: {},
+            handshake_in: {},
+            status: "forming",
+        };
+        // If peers are running next loops, notify them first
+        if (params.peers_running_next) {
+            for (const peerId of peers) {
+                try {
+                    const msg = JSON.stringify({
+                        _team_notify: true,
+                        team_id: teamId,
+                        git_repo: params.git_repo,
+                        team_members: params.agent_ids,
+                        message: `Team setup initiated. You will receive handshake tasks shortly. Create your branch in ${params.git_repo} and respond with your branch name.`,
+                    });
+                    await net.relayMessage({
+                        to: { network_id: "", server_id: "", agent_id: peerId },
+                        from: { network_id: "", server_id: state.getServerId() ?? "", agent_id: myId },
+                        content: msg,
+                    });
+                }
+                catch { /* best-effort notification */ }
+            }
+        }
+        // Create 0-budget handshake task for each peer
+        const handshakesCreated = [];
+        for (const peerId of peers) {
+            try {
+                const taskId = `t-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+                const content = {
+                    _handshake: true,
+                    team_id: teamId,
+                    git_repo: params.git_repo,
+                    from_agent: myId,
+                    team_members: params.agent_ids,
+                };
+                const task = await net.createTask({
+                    task_id: taskId,
+                    initiator_id: myId,
+                    content: { description: `Team handshake: ${myId} → ${peerId}` },
+                    domains: ["team-coordination"],
+                    budget: 0,
+                    max_concurrent_bidders: 1,
+                    max_depth: 0,
+                    invited_agent_ids: [peerId],
+                });
+                // Update task content with handshake marker via discussions
+                try {
+                    await net.updateDiscussions(task.id, myId, JSON.stringify(content));
+                }
+                catch { /* content is in description as fallback */ }
+                teamInfo.handshake_out[peerId] = task.id;
+                handshakesCreated.push(task.id);
+                state.updateTask({
+                    task_id: task.id,
+                    agent_id: myId,
+                    role: "initiator",
+                    status: task.status,
+                    domains: ["team-coordination"],
+                    description_summary: `Handshake → ${peerId}`,
+                    created_at: new Date().toISOString(),
+                });
+            }
+            catch (e) {
+                handshakesCreated.push(`FAILED(${peerId}): ${e.message ?? e}`);
+            }
+        }
+        state.addTeam(teamInfo);
+        results.push({ agent_id: myId, handshakes_created: handshakesCreated });
+    }
+    return ok({
+        team_id: teamId,
+        git_repo: params.git_repo,
+        agent_ids: params.agent_ids,
+        local_agents: myAgents,
+        results,
+        next_steps: [
+            "Each agent should now create their operation branch in the git repo.",
+            "When receiving handshake tasks (task_broadcast with _handshake marker), " +
+                "bid with price=0 and confidence=1, then submit_result with {branch: 'your-branch-name', _handshake_ack: true, team_id: '...'}.",
+            "When your handshake tasks get results, select_result to complete the handshake.",
+            "Team is ready when all peer branches are known.",
+        ],
+    });
+});
+// #43 eacn3_team_status — check team formation progress
+server.tool("eacn3_team_status", "Check the current status of a team: which handshakes are complete, which peer branches are known, and whether the team is ready.", {
+    team_id: z.string().describe("Team ID from eacn3_team_setup"),
+}, async (params) => {
+    const team = state.getTeam(params.team_id);
+    if (!team)
+        return err(`Team ${params.team_id} not found`);
+    const peers = team.agent_ids.filter((id) => id !== team.my_agent_id);
+    const handshakes_complete = peers.filter((id) => id in team.peer_branches);
+    const handshakes_pending = peers.filter((id) => !(id in team.peer_branches));
+    return ok({
+        team_id: team.team_id,
+        git_repo: team.git_repo,
+        status: team.status,
+        my_agent_id: team.my_agent_id,
+        my_branch: team.my_branch ?? null,
+        peer_branches: team.peer_branches,
+        handshakes_complete: handshakes_complete,
+        handshakes_pending: handshakes_pending,
+        ready: team.status === "ready",
     });
 });
+// #44 eacn3_team_set_branch — record this agent's operation branch
+server.tool("eacn3_team_set_branch", "Record this agent's git branch name for a team. Call after creating your branch in the git repo.", {
+    team_id: z.string().describe("Team ID"),
+    branch: z.string().describe("Branch name (e.g. 'agent/my-agent-id')"),
+}, async (params) => {
+    const team = state.getTeam(params.team_id);
+    if (!team)
+        return err(`Team ${params.team_id} not found`);
+    state.setTeamBranch(params.team_id, params.branch);
+    return ok({ team_id: params.team_id, branch: params.branch, message: "Branch recorded" });
+});
+// #40 eacn3_reverse_control_status
+server.tool("eacn3_reverse_control_status", "Get the current status of the MCP reverse control engine. Shows whether sampling is available, which agents are configured, pending directive count, and rate limiting info. Use for debugging reverse control behavior.", {}, async () => {
+    return ok(rc.getStatus());
+});
 // ---------------------------------------------------------------------------
-// Start
+// Long-polling helpers
 // ---------------------------------------------------------------------------
+function drainMatchingEvents(agentId, filterTypes) {
+    const all = state.drainEvents(agentId);
+    if (!filterTypes || filterTypes.length === 0)
+        return all;
+    const matching = [];
+    const remaining = [];
+    for (const e of all) {
+        if (filterTypes.includes(e.type)) {
+            matching.push(e);
+        }
+        else {
+            remaining.push(e);
+        }
+    }
+    if (remaining.length > 0)
+        state.pushEvents(agentId, remaining);
+    return matching;
+}
+function buildAwaitResponse(events) {
+    return {
+        count: events.length,
+        events: events.map((event) => {
+            const payload = event.payload;
+            switch (event.type) {
+                case "task_broadcast":
+                    return { event, suggested_action: `New task in [${(payload.domains ?? []).join(", ")}] budget=${payload.budget ?? "?"}. Evaluate and bid.`, suggested_tool: "eacn3_submit_bid", suggested_params: { task_id: event.task_id }, urgency: "high" };
+                case "direct_message":
+                    return { event, suggested_action: `Message from ${payload.from ?? "?"}: "${String(payload.content ?? "").slice(0, 200)}". Reply.`, suggested_tool: "eacn3_send_message", suggested_params: { to_agent_id: payload.from, task_id: event.task_id }, urgency: "high" };
+                case "subtask_completed":
+                    return { event, suggested_action: `Subtask ${payload.subtask_id ?? "?"} done. Fetch results.`, suggested_tool: "eacn3_get_task_results", suggested_params: { task_id: String(payload.subtask_id ?? event.task_id) }, urgency: "high" };
+                case "bid_request_confirmation":
+                    return { event, suggested_action: `Bid exceeded budget on ${event.task_id}. Approve/reject.`, suggested_tool: "eacn3_confirm_budget", suggested_params: { task_id: event.task_id }, urgency: "high" };
+                case "result_submitted":
+                    return { event, suggested_action: `Agent ${payload.agent_id ?? "?"} submitted result for ${event.task_id}. Review and decide: select with eacn3_select_result or wait for more.`, suggested_tool: "eacn3_get_task", suggested_params: { task_id: event.task_id }, urgency: "high" };
+                case "task_collected":
+                    return { event, suggested_action: `Task ${event.task_id}: all executors done. Retrieve and select.`, suggested_tool: "eacn3_get_task_results", suggested_params: { task_id: event.task_id }, urgency: "medium" };
+                case "task_timeout":
+                    return { event, suggested_action: `Task ${event.task_id} timed out. No action needed.`, suggested_tool: "eacn3_get_task", suggested_params: { task_id: event.task_id }, urgency: "low" };
+                default:
+                    return { event, suggested_action: `Event "${event.type}" on ${event.task_id}.`, suggested_tool: "eacn3_get_task", suggested_params: { task_id: event.task_id }, urgency: "low" };
+            }
+        }),
+    };
+}
 // ---------------------------------------------------------------------------
 // WS Event Callbacks — auto-actions when events arrive
 // ---------------------------------------------------------------------------
 function registerEventCallbacks() {
     ws.setEventCallback((agentId, event) => {
         const taskId = event.task_id;
+        // --- Reverse Control: try to handle event proactively ---
+        // This runs async; if it handles the event, it may take action
+        // (sampling, notification, auto-action) without waiting for polling.
+        rc.handleEvent(agentId, event).catch(() => { });
+        // --- Legacy behavior: local state updates + event buffering ---
+        // These still run regardless of reverse control, to keep local state consistent.
         switch (event.type) {
-            case "awaiting_retrieval":
+            case "task_collected":
                 // Task has results ready — update local status so dashboard/skills see it
                 state.updateTaskStatus(taskId, "awaiting_retrieval");
                 break;
@@ -867,7 +1406,8 @@ function registerEventCallbacks() {
                     net.getTaskResults(subtaskId, agentId)
                         .then((res) => {
                         // Buffer a synthetic event with the results for the skill to pick up
-                        state.pushEvents([{
+                        state.pushEvents(agentId, [{
+                                msg_id: crypto.randomUUID().replace(/-/g, ""),
                                 type: "subtask_completed",
                                 task_id: taskId,
                                 payload: { subtask_id: subtaskId, results: res.results },
@@ -878,12 +1418,12 @@ function registerEventCallbacks() {
                 }
                 break;
             }
-            case "timeout":
+            case "task_timeout":
                 // Task timed out — auto-report reputation event, update local status
                 state.updateTaskStatus(taskId, "no_one");
                 net.reportEvent(agentId, "task_timeout").catch(() => { });
                 break;
-            case "budget_confirmation":
+            case "bid_request_confirmation":
                 // Bid exceeded budget — mark in local state for initiator to handle
                 // The event stays in the buffer for /eacn3-bounty to surface
                 break;
@@ -932,7 +1472,8 @@ async function autoBidEvaluate(agentId, event) {
     }
     // Passed auto-filter — enrich the buffered event with a hint
     // The skill layer (/eacn3-bounty) will see this and can fast-track bidding
-    state.pushEvents([{
+    state.pushEvents(agentId, [{
+            msg_id: crypto.randomUUID().replace(/-/g, ""),
             type: "task_broadcast",
             task_id: taskId,
             payload: { ...payload, auto_match: true, matched_agent: agentId },
@@ -949,6 +1490,9 @@ async function main() {
     registerEventCallbacks();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Initialize reverse control engine with the underlying MCP Server instance.
+    // Must be called AFTER connect() so client capabilities are available.
+    rc.init(server.server ?? server);
 }
 main().catch((e) => {
     console.error("EACN3 MCP server failed to start:", e);