@agentlinkdev/agentlink 0.1.0

package/src/tools.ts

@@ -0,0 +1,352 @@
+import { Type } from "@sinclair/typebox";
+import { v4 as uuid } from "uuid";
+import type { AgentLinkConfig, AgentStatus } 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 { InviteManager } from "./invite.js";
+import type { JobManager } from "./jobs.js";
+import type { Logger } from "./mqtt-client.js";
+
+// ---------------------------------------------------------------------------
+// Tool result helper
+// ---------------------------------------------------------------------------
+
+function json(data: Record<string, unknown>) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Publish agent status to group
+// ---------------------------------------------------------------------------
+
+async function publishStatus(
+  config: AgentLinkConfig,
+  mqtt: MqttService,
+  groupId: string,
+): Promise<void> {
+  const status: AgentStatus = {
+    agent_id: config.agent.id,
+    owner: config.agent.description?.split("'s")[0] ?? config.agent.id,
+    status: "online",
+    capabilities: config.agent.capabilities.map((c) => ({
+      name: c.name,
+      description: c.description ?? c.name,
+      input_hint: c.input_hint ?? "",
+    })),
+    description: config.agent.description,
+    ts: new Date().toISOString(),
+  };
+
+  await mqtt.publish(
+    TOPICS.groupStatus(groupId, config.agent.id),
+    JSON.stringify(status),
+    { retain: true },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TypeBox Schemas
+// ---------------------------------------------------------------------------
+
+const CoordinateSchema = Type.Object({
+  goal: Type.String({ description: "What the user wants to accomplish" }),
+  done_when: Type.Optional(
+    Type.String({ description: "How to know when this is complete" }),
+  ),
+  participants: Type.Array(Type.String(), {
+    description: "Names or agent IDs of people to coordinate with",
+  }),
+});
+
+const SubmitJobSchema = Type.Object({
+  group_id: Type.String({ description: "The active group/coordination ID" }),
+  capability: Type.String({
+    description: "The capability to request (e.g. 'check_calendar')",
+  }),
+  target_agent: Type.Optional(
+    Type.String({
+      description: "Specific agent ID to target (optional — if omitted, routes by capability)",
+    }),
+  ),
+  text: Type.String({
+    description: "Natural language description of what you need",
+  }),
+});
+
+const InviteAgentSchema = Type.Object({
+  group_id: Type.String({ description: "The active group/coordination ID" }),
+  name_or_agent_id: Type.String({
+    description: "Contact name (e.g. 'Sara') or agent ID (e.g. 'sara-macbook')",
+  }),
+});
+
+const JoinGroupSchema = Type.Object({
+  invite_code: Type.String({
+    description: "The 6-character invite code (e.g. 'AB3X7K')",
+  }),
+});
+
+const CompleteSchema = Type.Object({
+  group_id: Type.String({ description: "The active group/coordination ID" }),
+  summary: Type.String({ description: "Final outcome summary" }),
+  success: Type.Optional(
+    Type.Boolean({
+      description: "Whether the goal was achieved",
+      default: true,
+    }),
+  ),
+});
+
+// ---------------------------------------------------------------------------
+// createTools
+// ---------------------------------------------------------------------------
+
+export function createTools(
+  config: AgentLinkConfig,
+  state: StateManager,
+  contacts: ContactsManager,
+  mqtt: MqttService,
+  invites: InviteManager,
+  jobs: JobManager,
+  logger: Logger,
+) {
+  function log(msg: string) {
+    if (config.outputMode === "debug") {
+      logger.info(`[AgentLink] ${msg}`);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // agentlink_coordinate
+  // -----------------------------------------------------------------------
+  const coordinateTool = {
+    name: "agentlink_coordinate",
+    label: "Coordinate",
+    description:
+      "Start coordinating with other people's agents. Use this when the user wants to do something that involves other people.",
+    parameters: CoordinateSchema,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const goal = params.goal as string;
+      const doneWhen = (params.done_when as string) ?? `${goal} — completed to user's satisfaction`;
+      const participants = params.participants as string[];
+
+      const resolved = participants.map((p) => ({
+        name: p,
+        agentId: contacts.resolve(p),
+      }));
+
+      const unresolved = resolved.filter((r) => !r.agentId);
+      if (unresolved.length > 0) {
+        return json({
+          error: `Unknown contacts: ${unresolved.map((u) => u.name).join(", ")}. Ask the user for their agent ID, or use agentlink_invite_agent with an agent_id.`,
+        });
+      }
+
+      const participantIds = resolved.map((r) => r.agentId!);
+      const groupId = uuid();
+      const intentId = uuid();
+
+      state.addGroup({
+        group_id: groupId,
+        driver: config.agent.id,
+        goal,
+        done_when: doneWhen,
+        intent_id: intentId,
+        participants: participantIds,
+        status: "active",
+        idle_turns: 0,
+        created_at: new Date().toISOString(),
+      });
+
+      await mqtt.subscribeGroup(groupId);
+      await publishStatus(config, mqtt, groupId);
+
+      for (const pid of participantIds) {
+        await invites.sendDirectInvite(pid, groupId, goal, doneWhen);
+        log(`Invite sent to ${contacts.getNameByAgentId(pid) ?? pid}`);
+      }
+
+      return json({
+        group_id: groupId,
+        intent_id: intentId,
+        participants: participantIds,
+        status: "invites_sent",
+        message: `Coordination started. Waiting for ${participantIds.length} agent(s) to join.`,
+      });
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // agentlink_submit_job
+  // -----------------------------------------------------------------------
+  const submitJobTool = {
+    name: "agentlink_submit_job",
+    label: "Submit Job",
+    description:
+      "Send a specific task to another agent. Use this to request actions like checking a calendar, searching for restaurants, etc.",
+    parameters: SubmitJobSchema,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const groupId = params.group_id as string;
+      const group = state.getGroup(groupId);
+      if (!group) return json({ error: "Group not found or already closed" });
+
+      const correlationId = await jobs.submitJob({
+        groupId,
+        intentId: group.intent_id,
+        targetAgentId: params.target_agent as string | undefined,
+        capability: params.capability as string,
+        text: params.text as string,
+      });
+
+      state.resetIdleTurns(groupId);
+
+      return json({
+        correlation_id: correlationId,
+        status: "requested",
+        message: `Job sent: ${params.capability}. Waiting for response (timeout: ${config.jobTimeoutMs / 1000}s).`,
+      });
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // agentlink_invite_agent
+  // -----------------------------------------------------------------------
+  const inviteAgentTool = {
+    name: "agentlink_invite_agent",
+    label: "Invite Agent",
+    description:
+      "Invite someone to join a coordination group. Use when adding new participants mid-coordination.",
+    parameters: InviteAgentSchema,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const groupId = params.group_id as string;
+      const group = state.getGroup(groupId);
+      if (!group) return json({ error: "Group not found" });
+
+      const nameOrId = params.name_or_agent_id as string;
+      const agentId = contacts.resolve(nameOrId);
+      if (!agentId) {
+        return json({ error: `Unknown contact: ${nameOrId}. Ask the user for their agent ID.` });
+      }
+
+      await invites.sendDirectInvite(agentId, groupId, group.goal, group.done_when);
+      log(`Invite sent to ${nameOrId}`);
+
+      return json({
+        group_id: groupId,
+        invited: agentId,
+        status: "invite_sent",
+      });
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // agentlink_join_group
+  // -----------------------------------------------------------------------
+  const joinGroupTool = {
+    name: "agentlink_join_group",
+    label: "Join Group",
+    description: "Join a coordination group using an invite code that was shared with you.",
+    parameters: JoinGroupSchema,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const code = params.invite_code as string;
+      const invite = await invites.resolveInviteCode(code);
+      if (!invite) return json({ error: "Invalid or expired invite code" });
+
+      const groupId = invite.group_id;
+
+      await mqtt.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(),
+      });
+
+      await publishStatus(config, mqtt, groupId);
+
+      const joinMsg = createEnvelope(config.agent.id, {
+        group_id: groupId,
+        to: "group",
+        type: "join",
+        payload: { text: `${config.agent.id} joined the group` },
+      });
+      await mqtt.publishEnvelope(TOPICS.groupSystem(groupId), joinMsg);
+
+      if (!contacts.resolve(invite.from)) {
+        contacts.add(invite.from, invite.from);
+      }
+
+      return json({
+        group_id: groupId,
+        driver: invite.from,
+        goal: invite.goal,
+        status: "joined",
+      });
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // agentlink_complete
+  // -----------------------------------------------------------------------
+  const completeTool = {
+    name: "agentlink_complete",
+    label: "Complete",
+    description:
+      "Declare that the coordination is complete. Only call this when the goal has been achieved or explicitly abandoned.",
+    parameters: CompleteSchema,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const groupId = params.group_id as string;
+      const summary = params.summary as string;
+      const success = (params.success as boolean) ?? true;
+
+      const group = state.getGroup(groupId);
+      if (!group) return json({ error: "Group not found" });
+
+      if (group.driver !== config.agent.id) {
+        return json({ error: "Only the driver agent can complete a coordination" });
+      }
+
+      const completionMsg = createEnvelope(config.agent.id, {
+        group_id: groupId,
+        to: "group",
+        type: "leave",
+        payload: {
+          text: summary,
+          status: success ? "completed" : "failed",
+        },
+      });
+      await mqtt.publishEnvelope(TOPICS.groupSystem(groupId), completionMsg);
+
+      await mqtt.unsubscribeGroup(groupId);
+
+      await mqtt.publish(
+        TOPICS.groupStatus(groupId, config.agent.id),
+        "",
+        { retain: true },
+      );
+
+      state.removeGroup(groupId);
+
+      log(`Coordination complete: ${summary}`);
+
+      return json({
+        group_id: groupId,
+        status: success ? "completed" : "failed",
+        summary,
+      });
+    },
+  };
+
+  return [coordinateTool, submitJobTool, inviteAgentTool, joinGroupTool, completeTool];
+}

package/src/types.ts

@@ -0,0 +1,258 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { v4 as uuid } from "uuid";
+
+// ---------------------------------------------------------------------------
+// Config types
+// ---------------------------------------------------------------------------
+
+export interface AgentLinkConfig {
+  brokerUrl: string;
+  brokerUsername?: string;
+  brokerPassword?: string;
+  agent: {
+    id: string;
+    description?: string;
+    capabilities: Capability[];
+  };
+  outputMode: "user" | "debug";
+  jobTimeoutMs: number;
+  dataDir: string;
+}
+
+export interface Capability {
+  name: string;
+  tool: string;
+  description?: string;
+  input_hint?: string;
+}
+
+export function resolveConfig(rawConfig: Record<string, unknown>): AgentLinkConfig {
+  const cfg = rawConfig as Record<string, unknown>;
+  const agent = cfg.agent as Record<string, unknown> | undefined;
+  const capabilities = (agent?.capabilities as Capability[] | undefined) ?? [];
+
+  // Resolve dataDir first — needed for persistent agent ID lookup
+  const dataDir = (cfg.data_dir as string) ?? path.join(os.homedir(), ".agentlink");
+
+  // 3-tier agent ID resolution:
+  // 1. Explicit agent.id from config (user-configured)
+  // 2. Persistent agent_id from <dataDir>/state.json (set by CLI setup)
+  // 3. Temp fallback agent-HOSTNAME-PID (dev without setup)
+  let agentId = agent?.id as string | undefined;
+  if (!agentId) {
+    try {
+      const stateFile = path.join(dataDir, "state.json");
+      if (fs.existsSync(stateFile)) {
+        const stateData = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+        if (stateData.agent_id && typeof stateData.agent_id === "string") {
+          agentId = stateData.agent_id;
+        }
+      }
+    } catch {
+      // state.json unreadable — fall through to temp ID
+    }
+  }
+  if (!agentId) {
+    agentId = `agent-${os.hostname().toLowerCase().replace(/[^a-z0-9-]/g, "")}-${process.pid}`;
+  }
+
+  return {
+    brokerUrl: (cfg.brokerUrl as string) ?? "mqtt://broker.emqx.io:1883",
+    brokerUsername: cfg.brokerUsername as string | undefined,
+    brokerPassword: cfg.brokerPassword as string | undefined,
+    agent: {
+      id: agentId,
+      description: agent?.description as string | undefined,
+      capabilities,
+    },
+    outputMode: (cfg.output_mode as "user" | "debug") ?? "user",
+    jobTimeoutMs: (cfg.job_timeout_ms as number) ?? 60_000,
+    dataDir,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Message envelope
+// ---------------------------------------------------------------------------
+
+export type MessageType = "chat" | "job_request" | "job_response" | "join" | "leave";
+
+export type JobStatus = "requested" | "completed" | "failed" | "awaiting_approval";
+
+export interface CoordinationHeader {
+  driver_agent_id: string;
+  goal: string;
+  done_when: string;
+}
+
+export interface ProposalPayload {
+  summary: string;
+  requires_approval: boolean;
+}
+
+export interface MessagePayload {
+  text?: string;
+  capability?: string;
+  status?: JobStatus;
+  result?: string;
+  proposal?: ProposalPayload;
+  [key: string]: unknown;
+}
+
+export interface MessageEnvelope {
+  v: 1;
+  id: string;
+  group_id: string;
+  intent_id: string;
+  from: string;
+  to: "group" | string;
+  type: MessageType;
+  correlation_id?: string;
+  coordination?: CoordinationHeader;
+  payload: MessagePayload;
+  ts: string;
+}
+
+// ---------------------------------------------------------------------------
+// Agent status (retained message)
+// ---------------------------------------------------------------------------
+
+export interface CapabilityAdvertisement {
+  name: string;
+  description: string;
+  input_hint: string;
+}
+
+export interface AgentStatus {
+  agent_id: string;
+  owner: string;
+  status: "online" | "offline";
+  capabilities: CapabilityAdvertisement[];
+  description?: string;
+  ts: string;
+}
+
+// ---------------------------------------------------------------------------
+// Invite types
+// ---------------------------------------------------------------------------
+
+export interface InviteMessage {
+  type: "invite";
+  group_id: string;
+  from: string;
+  goal: string;
+  done_when: string;
+  ts: string;
+}
+
+export interface InviteCodePayload {
+  group_id: string;
+  from: string;
+  goal: string;
+  created_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// State types
+// ---------------------------------------------------------------------------
+
+export interface GroupState {
+  group_id: string;
+  driver: string;
+  goal: string;
+  done_when: string;
+  intent_id: string;
+  participants: string[];
+  status: "active" | "closing";
+  idle_turns: number;
+  created_at: string;
+}
+
+export interface PendingJob {
+  correlation_id: string;
+  group_id: string;
+  target: string;
+  capability: string;
+  status: JobStatus;
+  sent_at: string;
+  text?: string;
+}
+
+export interface TimedOutJob extends PendingJob {
+  timed_out: true;
+}
+
+// ---------------------------------------------------------------------------
+// Helper: message construction
+// ---------------------------------------------------------------------------
+
+export function createEnvelope(
+  from: string,
+  overrides: Partial<MessageEnvelope> & Pick<MessageEnvelope, "group_id" | "to" | "type" | "payload">,
+): MessageEnvelope {
+  return {
+    v: 1,
+    id: uuid(),
+    intent_id: overrides.intent_id ?? uuid(),
+    from,
+    ts: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Topic helpers
+// ---------------------------------------------------------------------------
+
+export const TOPICS = {
+  inbox: (agentId: string) =>
+    `agentlink/agents/${agentId}/inbox`,
+
+  groupMessages: (groupId: string, agentId: string) =>
+    `agentlink/${groupId}/messages/${agentId}`,
+
+  groupMessagesWildcard: (groupId: string) =>
+    `agentlink/${groupId}/messages/+`,
+
+  groupStatus: (groupId: string, agentId: string) =>
+    `agentlink/${groupId}/status/${agentId}`,
+
+  groupStatusWildcard: (groupId: string) =>
+    `agentlink/${groupId}/status/+`,
+
+  groupSystem: (groupId: string) =>
+    `agentlink/${groupId}/system`,
+
+  groupAll: (groupId: string) =>
+    `agentlink/${groupId}/#`,
+
+  inviteCode: (code: string) =>
+    `agentlink/invites/${code}`,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isInviteMessage(msg: unknown): msg is InviteMessage {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    (msg as Record<string, unknown>).type === "invite" &&
+    typeof (msg as Record<string, unknown>).group_id === "string" &&
+    typeof (msg as Record<string, unknown>).from === "string"
+  );
+}
+
+export function isMessageEnvelope(msg: unknown): msg is MessageEnvelope {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  return (
+    m.v === 1 &&
+    typeof m.id === "string" &&
+    typeof m.from === "string" &&
+    typeof m.type === "string"
+  );
+}