agent-relay-sdk 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "agent-relay-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Agent Relay — WebSocket bus client, HTTP client, and shared types",
+  "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "author": "Edin Mujkanovic <edin@exelerus.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edimuj/agent-relay.git",
+    "directory": "sdk"
+  },
+  "keywords": [
+    "agent-relay",
+    "ai-agents",
+    "multi-agent",
+    "websocket",
+    "message-bus",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./http-client": {
+      "types": "./dist/http-client.d.ts",
+      "import": "./dist/http-client.js"
+    },
+    "./bus-client": {
+      "types": "./dist/bus-client.d.ts",
+      "import": "./dist/bus-client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/bus-client.ts

@@ -0,0 +1,337 @@
+import { EventEmitter } from "node:events";
+import {
+  type BusAgentStatus,
+  type BusRole,
+  type ErrorFrame,
+  type EventFrame,
+  type RegisteredFrame,
+  type ServerBusFrame,
+} from "./protocol.js";
+import { ReconnectionManager } from "./reconnect.js";
+
+export interface CursorStore {
+  load(): Promise<number | null>;
+  save(cursor: number): Promise<void>;
+}
+
+export interface BusClientOptions {
+  url: string;
+  role: BusRole;
+  componentId: string;
+  agentId?: string;
+  instanceId: string;
+  token?: string;
+  capabilities?: string[];
+  tags?: string[];
+  machine?: string;
+  meta?: Record<string, unknown>;
+  reconnect?: {
+    initialMs?: number;
+    maxMs?: number;
+    jitterMs?: number;
+  };
+  heartbeatIntervalMs?: number;
+  cursorStore?: CursorStore;
+  reconcile?: () => Promise<void>;
+}
+
+export interface BusClientEvents {
+  connected: () => void;
+  disconnected: (reason: string) => void;
+  reconnecting: (attempt: number, delayMs: number) => void;
+  registered: (epoch: number, cursor: number) => void;
+  event: (eventType: string, data: Record<string, unknown>, seq: number) => void;
+  command: (commandType: string, params: Record<string, unknown>, commandId: string) => void;
+  error: (code: string, message: string) => void;
+  "message.new": (message: unknown) => void;
+  "agent.status": (data: { id: string; status: string; previousStatus?: string }) => void;
+  "task.changed": (task: unknown) => void;
+}
+
+interface PendingFrame {
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+}
+
+class MemoryCursorStore implements CursorStore {
+  private value: number | null = null;
+  async load(): Promise<number | null> {
+    return this.value;
+  }
+  async save(cursor: number): Promise<void> {
+    this.value = cursor;
+  }
+}
+
+export class RelayBusClient extends EventEmitter {
+  private ws: WebSocket | null = null;
+  private registeredEpoch = 0;
+  private lastCursor = 0;
+  private serverCursor = 0;
+  private closed = false;
+  private connecting: Promise<void> | null = null;
+  private heartbeat?: Timer;
+  private readonly reconnect: ReconnectionManager;
+  private readonly cursorStore: CursorStore;
+  private readonly subscriptions = new Set<string>(["message.*", "agent.status", "task.*"]);
+  private readonly pending = new Map<string, PendingFrame>();
+
+  constructor(private readonly options: BusClientOptions) {
+    super();
+    this.reconnect = new ReconnectionManager({
+      initialMs: options.reconnect?.initialMs,
+      maxMs: options.reconnect?.maxMs,
+      jitterMs: options.reconnect?.jitterMs,
+    });
+    this.cursorStore = options.cursorStore ?? new MemoryCursorStore();
+  }
+
+  get connected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN && this.registeredEpoch > 0;
+  }
+
+  get epoch(): number {
+    return this.registeredEpoch;
+  }
+
+  get cursor(): number {
+    return this.lastCursor;
+  }
+
+  async connect(): Promise<void> {
+    if (this.connecting) return this.connecting;
+    this.closed = false;
+    this.connecting = this.connectLoop().finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    this.stopHeartbeat();
+    this.reconnect.cancel();
+    for (const pending of this.pending.values()) pending.reject(new Error("bus client closed"));
+    this.pending.clear();
+    if (this.ws && this.ws.readyState <= WebSocket.OPEN) this.ws.close();
+    this.ws = null;
+  }
+
+  status(update: { agentStatus: string; ready?: boolean; meta?: Record<string, unknown> }): void {
+    this.send({
+      type: "status",
+      payload: {
+        agentStatus: update.agentStatus as BusAgentStatus,
+        ready: update.ready,
+        meta: update.meta,
+      },
+    });
+  }
+
+  command(type: string, target: string, params: Record<string, unknown>): Promise<unknown> {
+    const id = crypto.randomUUID();
+    this.send({ type: "command", id, payload: { commandType: type, target, params } });
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+    });
+  }
+
+  async subscribe(events: string[], scopes?: string[]): Promise<void> {
+    for (const event of events) this.subscriptions.add(event);
+    const id = crypto.randomUUID();
+    this.send({ type: "subscribe", id, payload: { events, scopes } });
+    await Promise.resolve();
+  }
+
+  override on<K extends keyof BusClientEvents>(event: K, listener: BusClientEvents[K]): this {
+    return super.on(event, listener);
+  }
+
+  override off<K extends keyof BusClientEvents>(event: K, listener: BusClientEvents[K]): this {
+    return super.off(event, listener);
+  }
+
+  override once<K extends keyof BusClientEvents>(event: K, listener: BusClientEvents[K]): this {
+    return super.once(event, listener);
+  }
+
+  private async connectLoop(): Promise<void> {
+    while (!this.closed) {
+      try {
+        await this.openOnce();
+        this.reconnect.reset();
+        return;
+      } catch (error) {
+        if (this.closed) throw error;
+        const delayMs = this.reconnect.nextDelay();
+        this.emit("reconnecting", this.reconnect.attempt, delayMs);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+
+  private async openOnce(): Promise<void> {
+    const cursor = await this.cursorStore.load();
+    if (cursor !== null) this.lastCursor = cursor;
+
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl());
+      this.ws = ws;
+      let resolved = false;
+
+      ws.onopen = () => {
+        this.emit("connected");
+        this.sendRegister();
+      };
+      ws.onmessage = (message) => {
+        void this.handleMessage(message.data, () => {
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        });
+      };
+      ws.onerror = () => {
+        if (!resolved) reject(new Error("bus connection failed"));
+      };
+      ws.onclose = (event) => {
+        this.stopHeartbeat();
+        this.registeredEpoch = 0;
+        const reason = event.reason || `closed:${event.code}`;
+        this.emit("disconnected", reason);
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(reason));
+          return;
+        }
+        if (!this.closed) void this.connect();
+      };
+    });
+  }
+
+  private sendRegister(): void {
+    this.send({
+      type: "register",
+      id: crypto.randomUUID(),
+      payload: {
+        role: this.options.role,
+        componentId: this.options.componentId,
+        agentId: this.options.agentId,
+        instanceId: this.options.instanceId,
+        capabilities: this.options.capabilities ?? [],
+        tags: this.options.tags ?? [],
+        machine: this.options.machine ?? "unknown",
+        meta: this.options.meta ?? {},
+      },
+    });
+  }
+
+  private async handleMessage(data: unknown, onRegistered: () => void): Promise<void> {
+    let frame: ServerBusFrame;
+    try {
+      frame = JSON.parse(typeof data === "string" ? data : String(data)) as ServerBusFrame;
+    } catch {
+      this.emit("error", "INVALID_JSON", "server sent invalid JSON");
+      return;
+    }
+
+    if (frame.type === "registered") {
+      const payload = (frame as RegisteredFrame).payload;
+      const resumeFrom = this.lastCursor;
+      this.registeredEpoch = payload.epoch;
+      this.serverCursor = payload.cursor;
+      this.emit("registered", payload.epoch, payload.cursor);
+      this.send({ type: "subscribe", id: crypto.randomUUID(), payload: { events: [...this.subscriptions] } });
+      if (resumeFrom > 0 && resumeFrom < payload.cursor) {
+        this.send({ type: "resume", id: crypto.randomUUID(), payload: { since: resumeFrom } });
+      } else {
+        this.lastCursor = payload.cursor;
+        await this.cursorStore.save(this.lastCursor);
+      }
+      this.startHeartbeat();
+      onRegistered();
+      return;
+    }
+
+    if (frame.type === "event") {
+      await this.handleEvent((frame as EventFrame).payload);
+      return;
+    }
+
+    if (frame.type === "resumed") {
+      for (const event of frame.payload.events) await this.handleEvent(event);
+      return;
+    }
+
+    if (frame.type === "command.result") {
+      const pending = this.pending.get(frame.payload.commandId);
+      if (!pending) return;
+      this.pending.delete(frame.payload.commandId);
+      if (frame.payload.status === "succeeded") pending.resolve(frame.payload.result ?? null);
+      else pending.reject(new Error(frame.payload.error || frame.payload.status));
+      return;
+    }
+
+    if (frame.type === "error") {
+      const error = frame as ErrorFrame;
+      if (error.payload.code === "REPLAY_GAP") {
+        await this.options.reconcile?.();
+        this.lastCursor = this.serverCursor;
+        await this.cursorStore.save(this.lastCursor);
+      }
+      this.emit("error", error.payload.code, error.payload.message);
+      if (error.payload.frameId) {
+        const pending = this.pending.get(error.payload.frameId);
+        if (pending) {
+          this.pending.delete(error.payload.frameId);
+          pending.reject(new Error(error.payload.message));
+        }
+      }
+    }
+  }
+
+  private async handleEvent(event: EventFrame["payload"]): Promise<void> {
+    this.lastCursor = Math.max(this.lastCursor, event.seq);
+    await this.cursorStore.save(this.lastCursor);
+    this.emit("event", event.eventType, event.data, event.seq);
+    if (event.eventType === "command.requested") {
+      const command = isRecord(event.data.command) ? event.data.command : undefined;
+      if (command) {
+        const commandType = typeof command.type === "string" ? command.type : "";
+        const commandId = typeof command.id === "string" ? command.id : "";
+        const params = isRecord(command.params) ? command.params : {};
+        this.emit("command", commandType, params, commandId);
+      }
+    }
+    this.emit(event.eventType as keyof BusClientEvents, event.data as never);
+    if (event.eventType.startsWith("task.")) this.emit("task.changed", event.data);
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeat = setInterval(() => {
+      this.send({ type: "heartbeat", payload: { status: "online" } });
+    }, this.options.heartbeatIntervalMs ?? 30_000);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    this.heartbeat = undefined;
+  }
+
+  private send(frame: Record<string, unknown>): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.ws.send(JSON.stringify(frame));
+  }
+
+  private wsUrl(): string {
+    const url = new URL(this.options.url);
+    const token = this.options.token ?? process.env.AGENT_RELAY_TOKEN;
+    if (token && !url.searchParams.has("token")) url.searchParams.set("token", token);
+    return url.toString();
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/http-client.ts

@@ -0,0 +1,158 @@
+import type { AgentCard, PollQuery, RegisterAgentInput, SendMessageInput, Message } from "./types.js";
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  token?: string;
+  timeout?: number;
+}
+
+export class RelayHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    readonly statusText: string,
+    readonly body: string,
+  ) {
+    super(`relay ${method} ${path} failed: ${status}`);
+  }
+}
+
+export class RelayHttpClient {
+  private readonly baseUrl: string;
+  private readonly token?: string;
+  private readonly timeout: number;
+
+  constructor(options: HttpClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.token = options.token;
+    this.timeout = options.timeout ?? 10_000;
+  }
+
+  registerAgent(input: RegisterAgentInput): Promise<AgentCard> {
+    return this.json("POST", "/api/agents", input) as Promise<AgentCard>;
+  }
+
+  async getAgent(id: string): Promise<AgentCard | null> {
+    const response = await this.request("GET", `/api/agents/${encodeURIComponent(id)}`);
+    if (response.status === 404) return null;
+    return this.parseResponse(response, "GET", `/api/agents/${id}`) as Promise<AgentCard>;
+  }
+
+  listAgents(filter: { tag?: string; machine?: string; status?: string } = {}): Promise<AgentCard[]> {
+    const url = this.url("/api/agents");
+    for (const [key, value] of Object.entries(filter)) {
+      if (value) url.searchParams.set(key, value);
+    }
+    return this.jsonUrl("GET", url) as Promise<AgentCard[]>;
+  }
+
+  async heartbeat(agentId: string): Promise<void> {
+    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`);
+  }
+
+  async setStatus(agentId: string, status: string): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { status });
+  }
+
+  async setReady(agentId: string, ready: boolean): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready });
+  }
+
+  async setLabel(agentId: string, label: string | null): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/label`, { label });
+  }
+
+  async deleteAgent(agentId: string): Promise<void> {
+    await this.json("DELETE", `/api/agents/${encodeURIComponent(agentId)}`);
+  }
+
+  sendMessage(input: SendMessageInput): Promise<Message> {
+    return this.json("POST", "/api/messages", input) as Promise<Message>;
+  }
+
+  pollMessages(query: PollQuery): Promise<Message[]> {
+    const url = this.url("/api/messages");
+    url.searchParams.set("for", query.for);
+    if (query.since !== undefined) url.searchParams.set("since", String(query.since));
+    if (query.sinceId !== undefined) url.searchParams.set("sinceId", String(query.sinceId));
+    if (query.unread !== undefined) url.searchParams.set("unread", String(query.unread));
+    if (query.channel) url.searchParams.set("channel", query.channel);
+    if (query.limit !== undefined) url.searchParams.set("limit", String(query.limit));
+    return this.jsonUrl("GET", url) as Promise<Message[]>;
+  }
+
+  async getMessage(id: number): Promise<Message | null> {
+    const path = `/api/messages/${id}`;
+    const response = await this.request("GET", path);
+    if (response.status === 404) return null;
+    return this.parseResponse(response, "GET", path) as Promise<Message>;
+  }
+
+  getThread(messageId: number): Promise<Message[]> {
+    return this.json("GET", `/api/messages/${messageId}/thread`) as Promise<Message[]>;
+  }
+
+  async claimMessage(messageId: number, agentId: string): Promise<boolean> {
+    const path = `/api/messages/${messageId}/claim`;
+    const response = await this.request("POST", path, { agentId });
+    if (response.ok) return true;
+    if ([400, 404, 409].includes(response.status)) return false;
+    await this.parseResponse(response, "POST", path);
+    return false;
+  }
+
+  async markRead(messageId: number, agentId: string): Promise<void> {
+    await this.json("PATCH", `/api/messages/${messageId}`, { readBy: agentId });
+  }
+
+  async deleteMessage(messageId: number): Promise<void> {
+    await this.json("DELETE", `/api/messages/${messageId}`);
+  }
+
+  getCursor(): Promise<{ latestId: number }> {
+    return this.json("GET", "/api/messages/cursor") as Promise<{ latestId: number }>;
+  }
+
+  private json(method: string, path: string, body?: unknown): Promise<unknown> {
+    return this.jsonUrl(method, this.url(path), body);
+  }
+
+  private async jsonUrl(method: string, url: URL, body?: unknown): Promise<unknown> {
+    const response = await this.request(method, url, body);
+    return this.parseResponse(response, method, url.pathname);
+  }
+
+  private async request(method: string, pathOrUrl: string | URL, body?: unknown): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(pathOrUrl instanceof URL ? pathOrUrl : this.url(pathOrUrl), {
+        method,
+        headers: this.headers(body === undefined ? undefined : { "Content-Type": "application/json" }),
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async parseResponse(response: Response, method: string, path: string): Promise<unknown> {
+    if (!response.ok) {
+      const text = await response.text();
+      throw new RelayHttpError(method, path, response.status, response.statusText, text);
+    }
+    if (response.status === 204) return null;
+    return response.json().catch(() => null);
+  }
+
+  private headers(base: Record<string, string> = {}): Record<string, string> {
+    const token = this.token ?? process.env.AGENT_RELAY_TOKEN;
+    return token ? { ...base, "X-Agent-Relay-Token": token } : base;
+  }
+
+  private url(path: string): URL {
+    return new URL(path, this.baseUrl);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./protocol.js";
+export * from "./reconnect.js";
+export * from "./http-client.js";
+export * from "./bus-client.js";
+export * from "./provider-base.js";