@agentlinkdev/agentlink 0.1.0

package/src/mqtt-client.ts

@@ -0,0 +1,142 @@
+import mqtt from "mqtt";
+import type { AgentLinkConfig } from "./types.js";
+
+export interface PublishOptions {
+  retain?: boolean;
+  qos?: 0 | 1 | 2;
+}
+
+export interface MqttClient {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  subscribe(topic: string): Promise<void>;
+  unsubscribe(topic: string): Promise<void>;
+  publish(topic: string, payload: string | Buffer, options?: PublishOptions): Promise<void>;
+  onMessage(handler: (topic: string, payload: Buffer) => void): void;
+  isConnected(): boolean;
+}
+
+export interface Logger {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+
+export function createMqttClient(config: AgentLinkConfig, logger: Logger): MqttClient {
+  let client: mqtt.MqttClient | null = null;
+  const messageHandlers: Array<(topic: string, payload: Buffer) => void> = [];
+  let subscribedTopics: Set<string> = new Set();
+
+  return {
+    async connect() {
+      client = mqtt.connect(config.brokerUrl, {
+        username: config.brokerUsername,
+        password: config.brokerPassword,
+        clientId: `agentlink-${config.agent.id}-${Date.now()}`,
+        clean: true,
+        keepalive: 30,
+        reconnectPeriod: 5000,
+        connectTimeout: 10_000,
+      });
+
+      return new Promise<void>((resolve) => {
+        let resolved = false;
+
+        client!.on("connect", () => {
+          if (!resolved) {
+            resolved = true;
+            logger.info(`[AgentLink] Connected to broker: ${config.brokerUrl}`);
+            resolve();
+          } else {
+            logger.info(`[AgentLink] Reconnected to broker`);
+          }
+          // Resubscribe on every connect (clean:true means broker forgets subscriptions)
+          for (const topic of subscribedTopics) {
+            client!.subscribe(topic, { qos: 1 });
+          }
+        });
+
+        client!.on("error", (err: Error) => {
+          if (!resolved) {
+            // First connection attempt failed — start anyway, mqtt.js will keep retrying
+            resolved = true;
+            logger.warn(`[AgentLink] Broker unavailable (${err.message}), will retry in background`);
+            resolve();
+          } else {
+            logger.warn(`[AgentLink] MQTT error: ${err.message}`);
+          }
+        });
+
+        client!.on("message", (topic, payload) => {
+          for (const handler of messageHandlers) {
+            handler(topic, payload);
+          }
+        });
+
+        client!.on("reconnect", () => {
+          logger.info("[AgentLink] Reconnecting to broker...");
+        });
+
+        client!.on("offline", () => {
+          logger.warn("[AgentLink] Broker connection lost");
+        });
+      });
+    },
+
+    async disconnect() {
+      if (client) {
+        subscribedTopics.clear();
+        await new Promise<void>((resolve) => client!.end(false, {}, () => resolve()));
+        client = null;
+      }
+    },
+
+    async subscribe(topic) {
+      if (!client) throw new Error("MQTT client not initialized");
+      subscribedTopics.add(topic);
+      // If not connected, the topic is tracked and will be subscribed on (re)connect
+      if (!client.connected) return;
+      return new Promise<void>((resolve, reject) => {
+        client!.subscribe(topic, { qos: 1 }, (err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+
+    async unsubscribe(topic) {
+      if (!client) throw new Error("MQTT not connected");
+      subscribedTopics.delete(topic);
+      return new Promise<void>((resolve, reject) => {
+        client!.unsubscribe(topic, {}, (err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+
+    async publish(topic, payload, options = {}) {
+      if (!client) throw new Error("MQTT client not initialized");
+      if (!client.connected) throw new Error("MQTT broker not connected (retrying in background)");
+      return new Promise<void>((resolve, reject) => {
+        client!.publish(
+          topic,
+          payload,
+          { qos: options.qos ?? 1, retain: options.retain ?? false },
+          (err) => {
+            if (err) reject(err);
+            else resolve();
+          },
+        );
+      });
+    },
+
+    onMessage(handler) {
+      messageHandlers.push(handler);
+    },
+
+    isConnected() {
+      return client?.connected ?? false;
+    },
+  };
+}

package/src/mqtt-service.ts

@@ -0,0 +1,157 @@
+import { createMqttClient, type MqttClient, type PublishOptions, type Logger } from "./mqtt-client.js";
+import type { AgentLinkConfig, MessageEnvelope } from "./types.js";
+import { TOPICS, isInviteMessage, isMessageEnvelope } from "./types.js";
+import type { StateManager } from "./state.js";
+import type { ContactsManager } from "./contacts.js";
+
+export interface MqttService {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  publish(topic: string, payload: string, options?: PublishOptions): Promise<void>;
+  publishEnvelope(topic: string, envelope: MessageEnvelope): Promise<void>;
+  subscribeGroup(groupId: string): Promise<void>;
+  unsubscribeGroup(groupId: string): Promise<void>;
+  getClient(): MqttClient;
+  onGroupMessage(handler: (msg: MessageEnvelope) => void): void;
+  onInboxMessage(handler: (topic: string, msg: unknown) => void): void;
+  onStatusUpdate(handler: (msg: unknown) => void): void;
+  onSystemEvent(handler: (msg: unknown) => void): void;
+}
+
+export function createMqttService(
+  config: AgentLinkConfig,
+  state: StateManager,
+  contacts: ContactsManager,
+  logger: Logger,
+): MqttService {
+  const client = createMqttClient(config, logger);
+
+  const groupMessageHandlers: Array<(msg: MessageEnvelope) => void> = [];
+  const inboxHandlers: Array<(topic: string, msg: unknown) => void> = [];
+  const statusHandlers: Array<(msg: unknown) => void> = [];
+  const systemHandlers: Array<(msg: unknown) => void> = [];
+
+  function routeMessage(topic: string, payload: Buffer) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(payload.toString());
+    } catch {
+      logger.warn(`[AgentLink] Non-JSON message on ${topic}`);
+      return;
+    }
+
+    // Inbox: direct invites and jobs
+    if (topic === TOPICS.inbox(config.agent.id)) {
+      for (const handler of inboxHandlers) {
+        handler(topic, parsed);
+      }
+      return;
+    }
+
+    // Group messages
+    const groupMsgMatch = topic.match(/^agentlink\/([^/]+)\/messages\/.+$/);
+    if (groupMsgMatch) {
+      if (!isMessageEnvelope(parsed)) {
+        logger.warn(`[AgentLink] Malformed envelope on ${topic}`);
+        return;
+      }
+      if (parsed.from === config.agent.id) return; // ignore echo
+      for (const handler of groupMessageHandlers) {
+        handler(parsed);
+      }
+      return;
+    }
+
+    // Status updates
+    if (topic.match(/^agentlink\/[^/]+\/status\/.+$/)) {
+      for (const handler of statusHandlers) {
+        handler(parsed);
+      }
+      return;
+    }
+
+    // System events (join/leave/complete)
+    if (topic.match(/^agentlink\/[^/]+\/system$/)) {
+      for (const handler of systemHandlers) {
+        handler(parsed);
+      }
+      return;
+    }
+  }
+
+  return {
+    async start() {
+      await client.connect();
+
+      // Always subscribe to personal inbox
+      await client.subscribe(TOPICS.inbox(config.agent.id));
+
+      // Resubscribe to active groups from persisted state
+      for (const groupId of state.getActiveGroups()) {
+        await client.subscribe(TOPICS.groupAll(groupId));
+      }
+
+      // Route all inbound messages
+      client.onMessage(routeMessage);
+
+      // Check for timed-out jobs from before restart
+      const timedOut = state.checkTimeouts(config.jobTimeoutMs);
+      if (timedOut.length > 0) {
+        logger.info(`[AgentLink] ${timedOut.length} job(s) timed out during downtime`);
+      }
+    },
+
+    async stop() {
+      // Publish offline status for all active groups
+      for (const groupId of state.getActiveGroups()) {
+        const statusTopic = TOPICS.groupStatus(groupId, config.agent.id);
+        await client.publish(
+          statusTopic,
+          JSON.stringify({
+            agent_id: config.agent.id,
+            status: "offline",
+            ts: new Date().toISOString(),
+          }),
+          { retain: true },
+        );
+      }
+      await client.disconnect();
+    },
+
+    async publish(topic, payload, options) {
+      await client.publish(topic, payload, options);
+    },
+
+    async publishEnvelope(topic, envelope) {
+      await client.publish(topic, JSON.stringify(envelope), { qos: 1 });
+    },
+
+    async subscribeGroup(groupId) {
+      await client.subscribe(TOPICS.groupAll(groupId));
+    },
+
+    async unsubscribeGroup(groupId) {
+      await client.unsubscribe(TOPICS.groupAll(groupId));
+    },
+
+    getClient() {
+      return client;
+    },
+
+    onGroupMessage(handler) {
+      groupMessageHandlers.push(handler);
+    },
+
+    onInboxMessage(handler) {
+      inboxHandlers.push(handler);
+    },
+
+    onStatusUpdate(handler) {
+      statusHandlers.push(handler);
+    },
+
+    onSystemEvent(handler) {
+      systemHandlers.push(handler);
+    },
+  };
+}

package/src/routing.ts

@@ -0,0 +1,53 @@
+import type { MessageEnvelope, AgentStatus, Capability } from "./types.js";
+
+export interface Router {
+  resolveTarget(msg: MessageEnvelope, groupParticipants: AgentStatus[]): string[];
+}
+
+export function createRouter(): Router {
+  return {
+    resolveTarget(msg, groupParticipants) {
+      // Rule 1: Explicit target — route directly
+      if (msg.to !== "group") {
+        return [msg.to];
+      }
+
+      // Rule 2: Capability match — filter by capability
+      if (msg.payload.capability) {
+        const capName = msg.payload.capability;
+        return groupParticipants
+          .filter((p) => p.agent_id !== msg.from)
+          .filter((p) => p.capabilities.some((c) => c.name === capName))
+          .map((p) => p.agent_id);
+      }
+
+      // Rule 3: No capability — broadcast to all except sender
+      return groupParticipants
+        .filter((p) => p.agent_id !== msg.from)
+        .map((p) => p.agent_id);
+    },
+  };
+}
+
+/**
+ * Receiver-side: should this agent process the incoming message?
+ */
+export function shouldProcess(
+  msg: MessageEnvelope,
+  myAgentId: string,
+  myCapabilities: Capability[],
+): boolean {
+  // Always process if addressed to us directly
+  if (msg.to === myAgentId) return true;
+
+  // If broadcast with capability filter: only process if we have the capability
+  if (msg.to === "group" && msg.payload.capability) {
+    return myCapabilities.some((c) => c.name === msg.payload.capability);
+  }
+
+  // Broadcast without capability: process (group coordination)
+  if (msg.to === "group") return true;
+
+  // Addressed to someone else
+  return false;
+}

package/src/state.ts

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { GroupState, JobStatus, PendingJob, TimedOutJob } from "./types.js";
+
+export interface StateManager {
+  // Identity
+  getAgentId(): string | null;
+
+  // Pending joins (from CLI --join flag)
+  getPendingJoins(): string[];
+  removePendingJoin(code: string): void;
+
+  // Groups
+  addGroup(group: GroupState): void;
+  getGroup(groupId: string): GroupState | null;
+  removeGroup(groupId: string): void;
+  getActiveGroups(): string[];
+  updateGroup(groupId: string, updates: Partial<GroupState>): void;
+  incrementIdleTurns(groupId: string): number;
+  resetIdleTurns(groupId: string): void;
+
+  // Jobs
+  addJob(job: PendingJob): void;
+  getJob(correlationId: string): PendingJob | null;
+  completeJob(correlationId: string, status: JobStatus, result?: string): void;
+  removeJob(correlationId: string): void;
+  hasPendingJob(correlationId: string): boolean;
+  getJobsForGroup(groupId: string): PendingJob[];
+  checkTimeouts(timeoutMs: number): TimedOutJob[];
+}
+
+interface StateData {
+  agent_id?: string;
+  pending_joins?: string[];
+  groups: Record<string, GroupState>;
+  pending_jobs: Record<string, PendingJob>;
+}
+
+export function createState(dataDir: string): StateManager {
+  const filePath = path.join(dataDir, "state.json");
+  let data: StateData = {
+    groups: {},
+    pending_jobs: {},
+  };
+
+  if (fs.existsSync(filePath)) {
+    const loaded = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    data = {
+      ...data,
+      ...loaded,
+      groups: loaded.groups ?? data.groups,
+      pending_jobs: loaded.pending_jobs ?? data.pending_jobs,
+    };
+  }
+
+  function save() {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  }
+
+  return {
+    getAgentId() {
+      return data.agent_id ?? null;
+    },
+
+    getPendingJoins() {
+      return data.pending_joins ? [...data.pending_joins] : [];
+    },
+
+    removePendingJoin(code) {
+      if (data.pending_joins) {
+        data.pending_joins = data.pending_joins.filter((c) => c !== code);
+        save();
+      }
+    },
+
+    addGroup(group) {
+      data.groups[group.group_id] = group;
+      save();
+    },
+
+    getGroup(groupId) {
+      return data.groups[groupId] ?? null;
+    },
+
+    removeGroup(groupId) {
+      delete data.groups[groupId];
+      for (const [id, job] of Object.entries(data.pending_jobs)) {
+        if (job.group_id === groupId) delete data.pending_jobs[id];
+      }
+      save();
+    },
+
+    getActiveGroups() {
+      return Object.keys(data.groups).filter(
+        (id) => data.groups[id].status === "active",
+      );
+    },
+
+    updateGroup(groupId, updates) {
+      if (data.groups[groupId]) {
+        Object.assign(data.groups[groupId], updates);
+        save();
+      }
+    },
+
+    incrementIdleTurns(groupId) {
+      const group = data.groups[groupId];
+      if (!group) return 0;
+      group.idle_turns++;
+      save();
+      return group.idle_turns;
+    },
+
+    resetIdleTurns(groupId) {
+      if (data.groups[groupId]) {
+        data.groups[groupId].idle_turns = 0;
+        save();
+      }
+    },
+
+    addJob(job) {
+      data.pending_jobs[job.correlation_id] = job;
+      save();
+    },
+
+    getJob(correlationId) {
+      return data.pending_jobs[correlationId] ?? null;
+    },
+
+    completeJob(correlationId, status) {
+      const job = data.pending_jobs[correlationId];
+      if (job) {
+        job.status = status;
+        save();
+      }
+    },
+
+    removeJob(correlationId) {
+      delete data.pending_jobs[correlationId];
+      save();
+    },
+
+    hasPendingJob(correlationId) {
+      const job = data.pending_jobs[correlationId];
+      return !!job && job.status === "requested";
+    },
+
+    getJobsForGroup(groupId) {
+      return Object.values(data.pending_jobs).filter((j) => j.group_id === groupId);
+    },
+
+    checkTimeouts(timeoutMs) {
+      const now = Date.now();
+      const timedOut: TimedOutJob[] = [];
+      for (const job of Object.values(data.pending_jobs)) {
+        if (job.status === "requested") {
+          const elapsed = now - new Date(job.sent_at).getTime();
+          if (elapsed > timeoutMs) {
+            job.status = "failed";
+            timedOut.push({ ...job, timed_out: true });
+          }
+        }
+      }
+      if (timedOut.length > 0) save();
+      return timedOut;
+    },
+  };
+}