@agentlinkdev/agentlink 0.1.0

package/src/channel.ts

@@ -0,0 +1,91 @@
+import type { AgentLinkConfig, MessageEnvelope } from "./types.js";
+import { createEnvelope, TOPICS } from "./types.js";
+import type { StateManager } from "./state.js";
+import type { ContactsManager } from "./contacts.js";
+import type { MqttService } from "./mqtt-service.js";
+import type { Logger } from "./mqtt-client.js";
+
+export interface ChannelPlugin {
+  id: string;
+  meta: {
+    id: string;
+    label: string;
+    selectionLabel: string;
+    blurb: string;
+    aliases: string[];
+  };
+  capabilities: {
+    chatTypes: string[];
+  };
+  config: {
+    listAccountIds: () => string[];
+    resolveAccount: () => { accountId: string; enabled: boolean; configured: boolean };
+  };
+  outbound: {
+    deliveryMode: string;
+    sendText: (params: {
+      text: string;
+      threadId?: string;
+      channelId?: string;
+    }) => Promise<{ ok: boolean; error?: string }>;
+  };
+}
+
+export function createChannelPlugin(
+  config: AgentLinkConfig,
+  state: StateManager,
+  contacts: ContactsManager,
+  mqtt: MqttService,
+  logger: Logger,
+): ChannelPlugin {
+  return {
+    id: "agentlink",
+    meta: {
+      id: "agentlink",
+      label: "AgentLink",
+      selectionLabel: "AgentLink (Agent Coordination)",
+      blurb: "Agent-to-agent coordination channel",
+      aliases: ["al"],
+    },
+    capabilities: {
+      chatTypes: ["direct", "group"],
+    },
+    config: {
+      listAccountIds: () => [config.agent.id],
+      resolveAccount: () => ({
+        accountId: config.agent.id,
+        enabled: true,
+        configured: true,
+      }),
+    },
+    outbound: {
+      deliveryMode: "direct",
+      async sendText({ text, threadId, channelId }) {
+        if (!threadId) return { ok: false, error: "No group context" };
+
+        const group = state.getGroup(threadId);
+        if (!group) return { ok: false, error: "Group not found" };
+
+        const envelope = createEnvelope(config.agent.id, {
+          group_id: threadId,
+          intent_id: group.intent_id,
+          to: channelId ?? "group",
+          type: "chat",
+          payload: { text },
+        });
+
+        await mqtt.publishEnvelope(
+          TOPICS.groupMessages(threadId, config.agent.id),
+          envelope,
+        );
+
+        // Track idle turns for anti-deadlock (chat without job/proposal increments)
+        if (group.driver === config.agent.id) {
+          state.incrementIdleTurns(threadId);
+        }
+
+        return { ok: true };
+      },
+    },
+  };
+}

package/src/contacts.ts

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export interface ContactEntry {
+  agent_id: string;
+  added: string;
+}
+
+export interface ContactsManager {
+  resolve(nameOrId: string): string | null;
+  add(name: string, agentId: string): void;
+  remove(name: string): void;
+  has(name: string): boolean;
+  getAll(): Record<string, ContactEntry>;
+  getNameByAgentId(agentId: string): string | null;
+}
+
+export function createContacts(dataDir: string): ContactsManager {
+  const filePath = path.join(dataDir, "contacts.json");
+  let contacts: Record<string, ContactEntry> = {};
+
+  if (fs.existsSync(filePath)) {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    contacts = raw.contacts ?? {};
+  }
+
+  function save() {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ contacts }, null, 2));
+  }
+
+  return {
+    resolve(nameOrId) {
+      if (contacts[nameOrId]) return contacts[nameOrId].agent_id;
+      for (const entry of Object.values(contacts)) {
+        if (entry.agent_id === nameOrId) return nameOrId;
+      }
+      return null;
+    },
+
+    add(name, agentId) {
+      contacts[name] = {
+        agent_id: agentId,
+        added: new Date().toISOString().split("T")[0],
+      };
+      save();
+    },
+
+    remove(name) {
+      delete contacts[name];
+      save();
+    },
+
+    has(name) {
+      return name in contacts;
+    },
+
+    getAll() {
+      return { ...contacts };
+    },
+
+    getNameByAgentId(agentId) {
+      for (const [name, entry] of Object.entries(contacts)) {
+        if (entry.agent_id === agentId) return name;
+      }
+      return null;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,269 @@
+import type { AgentLinkConfig } from "./types.js";
+import { resolveConfig } from "./types.js";
+import { createContacts } from "./contacts.js";
+import { createState } from "./state.js";
+import { createMqttService } from "./mqtt-service.js";
+import { createInviteManager } from "./invite.js";
+import { createJobManager } from "./jobs.js";
+import { createTools } from "./tools.js";
+import { createChannelPlugin } from "./channel.js";
+import { shouldProcess } from "./routing.js";
+import type { Logger } from "./mqtt-client.js";
+
+// ---------------------------------------------------------------------------
+// Minimal OC Plugin API type (matches what we use from OpenClaw's PluginApi)
+// ---------------------------------------------------------------------------
+
+interface PluginApi {
+  config: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
+  logger: Logger;
+  registerService(service: { id: string; start: () => Promise<void>; stop: () => Promise<void> }): void;
+  registerTool(tool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute: (_id: string, params: Record<string, unknown>) => Promise<{
+      content: Array<{ type: "text"; text: string }>;
+      details: unknown;
+    }>;
+  }): void;
+  registerChannel?(registration: { plugin: unknown }): void;
+  registerCli?(registrar: (ctx: { program: unknown }) => void, opts?: { commands?: string[] }): void;
+  on?(hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }): void;
+  runtime?: {
+    executeTool(params: {
+      toolName: string;
+      params: Record<string, unknown>;
+      ctx?: unknown;
+    }): Promise<unknown>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Plugin definition object (preferred OC pattern)
+// ---------------------------------------------------------------------------
+
+export default {
+  id: "agentlink",
+  name: "AgentLink",
+  description: "Agent-to-agent coordination over MQTT",
+  register,
+};
+
+function register(api: PluginApi) {
+  const config = resolveConfig(api.pluginConfig ?? {});
+  const contacts = createContacts(config.dataDir);
+  const state = createState(config.dataDir);
+  const logger = api.logger;
+
+  function log(msg: string) {
+    if (config.outputMode === "debug") {
+      logger.info(`[AgentLink] ${msg}`);
+    }
+  }
+
+  const mqttService = createMqttService(config, state, contacts, logger);
+
+  const invites = createInviteManager(config, mqttService);
+
+  // executeTool bridge: calls the local OC tool when a job_request arrives
+  const executeTool = api.runtime
+    ? async (toolId: string, input: string): Promise<string> => {
+        const result = await api.runtime!.executeTool({
+          toolName: toolId,
+          params: { input },
+        });
+        return typeof result === "string" ? result : JSON.stringify(result);
+      }
+    : undefined;
+
+  const jobs = createJobManager(config, state, mqttService, logger, executeTool);
+
+  // Wire inbound message handling
+  mqttService.onGroupMessage((msg) => {
+    // Check if this agent should process the message
+    if (!shouldProcess(msg, config.agent.id, config.agent.capabilities)) {
+      return;
+    }
+
+    if (msg.type === "job_request") {
+      jobs.handleJobRequest(msg);
+      return;
+    }
+
+    if (msg.type === "job_response" && msg.correlation_id && state.hasPendingJob(msg.correlation_id)) {
+      jobs.handleJobResponse(msg);
+      return;
+    }
+
+    // General coordination message — log it
+    const senderName = contacts.getNameByAgentId(msg.from) ?? msg.from;
+    log(`Message from ${senderName}: ${msg.payload.text ?? "(no text)"}`);
+  });
+
+  mqttService.onInboxMessage((_topic, raw) => {
+    const msg = raw as Record<string, unknown>;
+    if (msg.type === "invite") {
+      log(`Invite received from ${msg.from}: "${msg.goal}"`);
+      // For V1: auto-join if from known contact
+      const fromId = msg.from as string;
+      if (contacts.resolve(fromId)) {
+        log(`Auto-joining (known contact: ${contacts.getNameByAgentId(fromId) ?? fromId})`);
+        // Auto-join logic handled by the agent's LLM calling agentlink_join_group
+        // or we could auto-accept here for known contacts
+      }
+    }
+  });
+
+  mqttService.onSystemEvent((raw) => {
+    const msg = raw as Record<string, unknown>;
+    if (msg && typeof msg === "object" && "type" in msg) {
+      const envelope = msg as Record<string, unknown>;
+      if (envelope.type === "join") {
+        const from = envelope.from as string;
+        const groupId = envelope.group_id as string;
+        const group = state.getGroup(groupId);
+        if (group && !group.participants.includes(from)) {
+          group.participants.push(from);
+          state.updateGroup(groupId, { participants: group.participants });
+        }
+        log(`${contacts.getNameByAgentId(from) ?? from} joined group ${groupId}`);
+      }
+      if (envelope.type === "leave") {
+        const groupId = envelope.group_id as string;
+        // If this is a completion message from the driver, clean up
+        const group = state.getGroup(groupId);
+        if (group && envelope.from !== config.agent.id) {
+          mqttService.unsubscribeGroup(groupId);
+          state.removeGroup(groupId);
+          log(`Group ${groupId} closed by driver`);
+        }
+      }
+    }
+  });
+
+  // Background MQTT connection
+  api.registerService({
+    id: "agentlink-mqtt",
+    start: async () => {
+      await mqttService.start();
+
+      // Process pending joins from CLI --join flag
+      const pendingJoins = state.getPendingJoins();
+      for (const code of pendingJoins) {
+        try {
+          log(`Processing pending join: ${code}`);
+          const invite = await invites.resolveInviteCode(code);
+          if (invite) {
+            const groupId = invite.group_id;
+            await mqttService.subscribeGroup(groupId);
+            state.addGroup({
+              group_id: groupId,
+              driver: invite.from,
+              goal: invite.goal,
+              done_when: "",
+              intent_id: "",
+              participants: [invite.from],
+              status: "active",
+              idle_turns: 0,
+              created_at: new Date().toISOString(),
+            });
+            if (!contacts.resolve(invite.from)) {
+              contacts.add(invite.from, invite.from);
+            }
+            state.removePendingJoin(code);
+            log(`Auto-joined group from setup: ${code}`);
+          } else {
+            log(`Pending join ${code}: invite not found (will retry next restart)`);
+          }
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          log(`Failed to auto-join ${code}: ${msg}`);
+        }
+      }
+    },
+    stop: () => mqttService.stop(),
+  });
+
+  // Register the 5 agent tools
+  const tools = createTools(config, state, contacts, mqttService, invites, jobs, logger);
+  for (const tool of tools) {
+    api.registerTool(tool);
+  }
+
+  // Optional channel registration
+  if (api.registerChannel) {
+    const channelPlugin = createChannelPlugin(config, state, contacts, mqttService, logger);
+    api.registerChannel({ plugin: channelPlugin });
+  }
+
+  // Anti-deadlock system prompt injection
+  if (api.on) {
+    api.on("before_prompt_build", () => {
+      const activeGroups = state.getActiveGroups();
+      if (activeGroups.length === 0) return {};
+
+      const driverGroups = activeGroups
+        .map((id) => state.getGroup(id))
+        .filter((g) => g?.driver === config.agent.id);
+
+      if (driverGroups.length === 0) return {};
+
+      let prompt = "\n\n## AgentLink Coordination Rules (MANDATORY)\n";
+      prompt += "You are the DRIVER of active coordination(s). You MUST follow these rules:\n";
+      prompt += "1. Issue direct jobs (agentlink_submit_job) instead of asking open-ended questions.\n";
+      prompt += "2. Make concrete proposals with specifics (time, place, price), not vague suggestions.\n";
+      prompt += "3. After 3 turns of discussion without a job, proposal, or completion, you MUST force progress.\n";
+      prompt += "4. Declare completion (agentlink_complete) as soon as the done_when condition is met.\n";
+      prompt += "5. Hub-and-spoke: you mediate all coordination. Participants respond to you, not each other.\n\n";
+
+      for (const group of driverGroups) {
+        if (!group) continue;
+        prompt += `Active: "${group.goal}" | Done when: "${group.done_when}" | Idle turns: ${group.idle_turns}/3\n`;
+        if (group.idle_turns >= 3) {
+          prompt += `  WARNING: 3 idle turns reached. You MUST take concrete action NOW.\n`;
+        }
+      }
+
+      return { appendSystemContext: prompt };
+    });
+  }
+
+  // CLI commands
+  if (api.registerCli) {
+    api.registerCli(
+      ({ program }: { program: any }) => {
+        const cmd = program.command("agentlink").description("AgentLink agent coordination");
+        cmd
+          .command("status")
+          .description("Show AgentLink connection and group status")
+          .action(() => {
+            console.log(`Agent ID: ${config.agent.id}`);
+            console.log(`Broker: ${config.brokerUrl}`);
+            console.log(`Connected: ${mqttService.getClient().isConnected()}`);
+            console.log(`Active groups: ${state.getActiveGroups().length}`);
+            console.log(
+              `Capabilities: ${config.agent.capabilities.map((c) => c.name).join(", ") || "none"}`,
+            );
+          });
+        cmd
+          .command("contacts")
+          .description("List known contacts")
+          .action(() => {
+            const all = contacts.getAll();
+            const entries = Object.entries(all);
+            if (entries.length === 0) {
+              console.log("No contacts.");
+              return;
+            }
+            for (const [name, entry] of entries) {
+              console.log(`${name} -> ${entry.agent_id} (added ${entry.added})`);
+            }
+          });
+      },
+      { commands: ["agentlink"] },
+    );
+  }
+}

package/src/invite.ts

@@ -0,0 +1,99 @@
+import { v4 as uuid } from "uuid";
+import type { AgentLinkConfig, InviteMessage, InviteCodePayload } from "./types.js";
+import { TOPICS } from "./types.js";
+import type { MqttService } from "./mqtt-service.js";
+
+export interface InviteCodeResult {
+  code: string;
+  shareableMessage: string;
+}
+
+export interface InviteManager {
+  createInviteCode(groupId: string, from: string, goal: string): Promise<InviteCodeResult>;
+  resolveInviteCode(code: string): Promise<InviteCodePayload | null>;
+  sendDirectInvite(targetAgentId: string, groupId: string, goal: string, doneWhen: string): Promise<void>;
+}
+
+export function createInviteManager(
+  config: AgentLinkConfig,
+  mqtt: MqttService,
+): InviteManager {
+  return {
+    async createInviteCode(groupId, from, goal) {
+      const code = uuid().replace(/-/g, "").substring(0, 6).toUpperCase();
+
+      const payload: InviteCodePayload = {
+        group_id: groupId,
+        from,
+        goal,
+        created_at: new Date().toISOString(),
+      };
+
+      await mqtt.publish(
+        TOPICS.inviteCode(code),
+        JSON.stringify(payload),
+        { retain: true, qos: 1 },
+      );
+
+      const shareableMessage = [
+        `Join my agent coordination: ${code}`,
+        `1. Install AgentLink: openclaw plugins install @agentlinkdev/openclaw`,
+        `2. Tell your agent: "Join AgentLink group ${code}"`,
+      ].join("\n");
+
+      return { code, shareableMessage };
+    },
+
+    async resolveInviteCode(code) {
+      return new Promise((resolve) => {
+        const topic = TOPICS.inviteCode(code);
+        let resolved = false;
+
+        const timeout = setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            resolve(null);
+          }
+        }, 5000);
+
+        const handler = (msgTopic: string, payload: Buffer) => {
+          if (msgTopic === topic && !resolved) {
+            resolved = true;
+            clearTimeout(timeout);
+            try {
+              resolve(JSON.parse(payload.toString()));
+            } catch {
+              resolve(null);
+            }
+          }
+        };
+
+        mqtt.getClient().onMessage(handler);
+        mqtt.getClient().subscribe(topic).catch(() => {
+          if (!resolved) {
+            resolved = true;
+            clearTimeout(timeout);
+            resolve(null);
+          }
+        });
+      });
+    },
+
+    async sendDirectInvite(targetAgentId, groupId, goal, doneWhen) {
+      const invite: InviteMessage = {
+        type: "invite",
+        group_id: groupId,
+        from: config.agent.id,
+        goal,
+        done_when: doneWhen,
+        ts: new Date().toISOString(),
+      };
+
+      await mqtt.publish(
+        TOPICS.inbox(targetAgentId),
+        JSON.stringify(invite),
+        { qos: 1 },
+      );
+    },
+  };
+}

package/src/jobs.ts

@@ -0,0 +1,156 @@
+import { v4 as uuid } from "uuid";
+import type { AgentLinkConfig, MessageEnvelope } from "./types.js";
+import { createEnvelope, TOPICS } from "./types.js";
+import type { StateManager } from "./state.js";
+import type { MqttService } from "./mqtt-service.js";
+import type { Logger } from "./mqtt-client.js";
+
+export interface SubmitJobParams {
+  groupId: string;
+  intentId: string;
+  targetAgentId?: string;
+  capability: string;
+  text: string;
+}
+
+export interface JobManager {
+  submitJob(params: SubmitJobParams): Promise<string>;
+  handleJobResponse(msg: MessageEnvelope): void;
+  handleJobRequest(msg: MessageEnvelope): Promise<MessageEnvelope | null>;
+}
+
+export function createJobManager(
+  config: AgentLinkConfig,
+  state: StateManager,
+  mqtt: MqttService,
+  logger: Logger,
+  executeTool?: (toolId: string, input: string) => Promise<string>,
+): JobManager {
+  return {
+    async submitJob(params) {
+      const correlationId = uuid();
+      const envelope = createEnvelope(config.agent.id, {
+        group_id: params.groupId,
+        intent_id: params.intentId,
+        to: params.targetAgentId ?? "group",
+        type: "job_request",
+        correlation_id: correlationId,
+        payload: {
+          text: params.text,
+          capability: params.capability,
+        },
+      });
+
+      state.addJob({
+        correlation_id: correlationId,
+        group_id: params.groupId,
+        target: params.targetAgentId ?? "group",
+        capability: params.capability,
+        status: "requested",
+        sent_at: envelope.ts,
+        text: params.text,
+      });
+
+      await mqtt.publishEnvelope(
+        TOPICS.groupMessages(params.groupId, config.agent.id),
+        envelope,
+      );
+
+      // Start timeout timer
+      setTimeout(() => {
+        if (state.hasPendingJob(correlationId)) {
+          state.completeJob(correlationId, "failed");
+          logger.info(`[AgentLink] Job ${correlationId} timed out (${params.capability})`);
+        }
+      }, config.jobTimeoutMs);
+
+      return correlationId;
+    },
+
+    handleJobResponse(msg) {
+      if (!msg.correlation_id) return;
+      const job = state.getJob(msg.correlation_id);
+      if (!job) return;
+
+      const status = msg.payload.status ?? "completed";
+      state.completeJob(msg.correlation_id, status);
+      logger.info(
+        `[AgentLink] Job ${msg.correlation_id} ${status}: ${msg.payload.result ?? "(no result)"}`,
+      );
+    },
+
+    async handleJobRequest(msg) {
+      const capability = msg.payload.capability;
+      if (!capability) return null;
+
+      const cap = config.agent.capabilities.find((c) => c.name === capability);
+      if (!cap) {
+        const response = createEnvelope(config.agent.id, {
+          group_id: msg.group_id,
+          intent_id: msg.intent_id,
+          to: msg.from,
+          type: "job_response",
+          correlation_id: msg.correlation_id,
+          payload: {
+            status: "failed",
+            result: `Capability '${capability}' not available`,
+            capability,
+          },
+        });
+        await mqtt.publishEnvelope(
+          TOPICS.groupMessages(msg.group_id, config.agent.id),
+          response,
+        );
+        return response;
+      }
+
+      logger.info(`[AgentLink] Running local tool: ${cap.tool} for capability: ${capability}`);
+
+      let result: string;
+      try {
+        if (executeTool) {
+          result = await executeTool(cap.tool, msg.payload.text ?? "");
+        } else {
+          result = `Tool execution not available (no executeTool provided)`;
+        }
+      } catch (err: unknown) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const response = createEnvelope(config.agent.id, {
+          group_id: msg.group_id,
+          intent_id: msg.intent_id,
+          to: msg.from,
+          type: "job_response",
+          correlation_id: msg.correlation_id,
+          payload: {
+            status: "failed",
+            result: `Tool execution error: ${errMsg}`,
+            capability,
+          },
+        });
+        await mqtt.publishEnvelope(
+          TOPICS.groupMessages(msg.group_id, config.agent.id),
+          response,
+        );
+        return response;
+      }
+
+      const response = createEnvelope(config.agent.id, {
+        group_id: msg.group_id,
+        intent_id: msg.intent_id,
+        to: msg.from,
+        type: "job_response",
+        correlation_id: msg.correlation_id,
+        payload: {
+          status: "completed",
+          result,
+          capability,
+        },
+      });
+      await mqtt.publishEnvelope(
+        TOPICS.groupMessages(msg.group_id, config.agent.id),
+        response,
+      );
+      return response;
+    },
+  };
+}