agent-relay-sdk 0.1.0

package/src/protocol.ts

@@ -0,0 +1,286 @@
+export interface BusFrame {
+  type: string;
+  id?: string;
+  payload: unknown;
+}
+
+export type BusRole = "provider" | "channel" | "orchestrator" | "integration";
+export type BusAgentStatus = "idle" | "busy" | "online" | "offline";
+
+export interface RegisterFrame extends BusFrame {
+  type: "register";
+  id: string;
+  payload: {
+    role: BusRole;
+    componentId: string;
+    agentId?: string;
+    instanceId: string;
+    capabilities: string[];
+    tags: string[];
+    machine: string;
+    meta: Record<string, unknown>;
+  };
+}
+
+export interface HeartbeatFrame extends BusFrame {
+  type: "heartbeat";
+  payload: {
+    status: Exclude<BusAgentStatus, "offline">;
+    meta?: Record<string, unknown>;
+  };
+}
+
+export interface CommandFrame extends BusFrame {
+  type: "command";
+  id: string;
+  payload: {
+    commandType: string;
+    target: string;
+    params: Record<string, unknown>;
+  };
+}
+
+export interface SubscribeFrame extends BusFrame {
+  type: "subscribe";
+  id: string;
+  payload: {
+    events: string[];
+    scopes?: string[];
+  };
+}
+
+export interface StatusFrame extends BusFrame {
+  type: "status";
+  payload: {
+    agentStatus: BusAgentStatus;
+    ready?: boolean;
+    meta?: Record<string, unknown>;
+  };
+}
+
+export interface AckFrame extends BusFrame {
+  type: "ack";
+  payload: {
+    frameId: string;
+  };
+}
+
+export interface ResumeFrame extends BusFrame {
+  type: "resume";
+  id: string;
+  payload: {
+    since: number;
+  };
+}
+
+export interface RegisteredFrame extends BusFrame {
+  type: "registered";
+  payload: {
+    epoch: number;
+    cursor: number;
+    sessionId: string;
+  };
+}
+
+export interface EventPayload {
+  seq: number;
+  eventType: string;
+  source: string;
+  subject?: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+export interface EventFrame extends BusFrame {
+  type: "event";
+  id?: string;
+  payload: EventPayload;
+}
+
+export interface CommandResultFrame extends BusFrame {
+  type: "command.result";
+  payload: {
+    commandId: string;
+    status: "succeeded" | "failed" | "rejected" | "timed_out";
+    result?: Record<string, unknown>;
+    error?: string;
+  };
+}
+
+export interface ResumedFrame extends BusFrame {
+  type: "resumed";
+  payload: {
+    events: EventPayload[];
+    fromSeq: number;
+    toSeq: number;
+  };
+}
+
+export interface ErrorFrame extends BusFrame {
+  type: "error";
+  payload: {
+    frameId?: string;
+    code: string;
+    message: string;
+  };
+}
+
+export type ClientBusFrame =
+  | RegisterFrame
+  | HeartbeatFrame
+  | CommandFrame
+  | SubscribeFrame
+  | StatusFrame
+  | AckFrame
+  | ResumeFrame;
+
+export type ServerBusFrame =
+  | RegisteredFrame
+  | EventFrame
+  | CommandResultFrame
+  | ResumedFrame
+  | ErrorFrame;
+
+export class BusProtocolError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function isRegisterFrame(f: BusFrame): f is RegisterFrame { return f.type === "register"; }
+export function isHeartbeatFrame(f: BusFrame): f is HeartbeatFrame { return f.type === "heartbeat"; }
+export function isCommandFrame(f: BusFrame): f is CommandFrame { return f.type === "command"; }
+export function isSubscribeFrame(f: BusFrame): f is SubscribeFrame { return f.type === "subscribe"; }
+export function isStatusFrame(f: BusFrame): f is StatusFrame { return f.type === "status"; }
+export function isAckFrame(f: BusFrame): f is AckFrame { return f.type === "ack"; }
+export function isResumeFrame(f: BusFrame): f is ResumeFrame { return f.type === "resume"; }
+
+export function parseBusFrame(data: string | ArrayBuffer | Uint8Array): BusFrame {
+  const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new BusProtocolError("INVALID_JSON", "frame must be valid JSON");
+  }
+  if (!isRecord(parsed) || typeof parsed.type !== "string") {
+    throw new BusProtocolError("INVALID_FRAME", "frame must be an object with a string type");
+  }
+  if (!("payload" in parsed)) {
+    throw new BusProtocolError("INVALID_FRAME", "frame payload is required");
+  }
+  if ("id" in parsed && parsed.id !== undefined && typeof parsed.id !== "string") {
+    throw new BusProtocolError("INVALID_FRAME", "frame id must be a string");
+  }
+  return parsed as unknown as BusFrame;
+}
+
+export function validateClientFrame(frame: BusFrame): ClientBusFrame {
+  switch (frame.type) {
+    case "register":
+      requireId(frame);
+      requireRegisterPayload(frame.payload);
+      return frame as RegisterFrame;
+    case "heartbeat":
+      requireHeartbeatPayload(frame.payload);
+      return frame as HeartbeatFrame;
+    case "command":
+      requireId(frame);
+      requireCommandPayload(frame.payload);
+      return frame as CommandFrame;
+    case "subscribe":
+      requireId(frame);
+      requireSubscribePayload(frame.payload);
+      return frame as SubscribeFrame;
+    case "status":
+      requireStatusPayload(frame.payload);
+      return frame as StatusFrame;
+    case "ack":
+      requireAckPayload(frame.payload);
+      return frame as AckFrame;
+    case "resume":
+      requireId(frame);
+      requireResumePayload(frame.payload);
+      return frame as ResumeFrame;
+    default:
+      throw new BusProtocolError("UNKNOWN_FRAME", `unsupported frame type: ${frame.type}`);
+  }
+}
+
+function requireId(frame: BusFrame): asserts frame is BusFrame & { id: string } {
+  if (!frame.id) throw new BusProtocolError("MISSING_ID", `${frame.type} frame id is required`);
+}
+
+function requireRegisterPayload(payload: unknown): void {
+  if (!isRecord(payload)) throw invalidPayload("register");
+  if (!isRole(payload.role)) throw invalidPayload("register.role");
+  requireString(payload.componentId, "register.componentId");
+  requireString(payload.instanceId, "register.instanceId");
+  if (payload.agentId !== undefined) requireString(payload.agentId, "register.agentId");
+  requireStringArray(payload.capabilities, "register.capabilities");
+  requireStringArray(payload.tags, "register.tags");
+  requireString(payload.machine, "register.machine");
+  if (!isRecord(payload.meta)) throw invalidPayload("register.meta");
+}
+
+function requireHeartbeatPayload(payload: unknown): void {
+  if (!isRecord(payload) || !["idle", "busy", "online"].includes(String(payload.status))) {
+    throw invalidPayload("heartbeat");
+  }
+  if (payload.meta !== undefined && !isRecord(payload.meta)) throw invalidPayload("heartbeat.meta");
+}
+
+function requireCommandPayload(payload: unknown): void {
+  if (!isRecord(payload)) throw invalidPayload("command");
+  requireString(payload.commandType, "command.commandType");
+  requireString(payload.target, "command.target");
+  if (!isRecord(payload.params)) throw invalidPayload("command.params");
+}
+
+function requireSubscribePayload(payload: unknown): void {
+  if (!isRecord(payload)) throw invalidPayload("subscribe");
+  requireStringArray(payload.events, "subscribe.events");
+  if (payload.scopes !== undefined) requireStringArray(payload.scopes, "subscribe.scopes");
+}
+
+function requireStatusPayload(payload: unknown): void {
+  if (!isRecord(payload) || !["idle", "busy", "online", "offline"].includes(String(payload.agentStatus))) {
+    throw invalidPayload("status");
+  }
+  if (payload.ready !== undefined && typeof payload.ready !== "boolean") throw invalidPayload("status.ready");
+  if (payload.meta !== undefined && !isRecord(payload.meta)) throw invalidPayload("status.meta");
+}
+
+function requireAckPayload(payload: unknown): void {
+  if (!isRecord(payload)) throw invalidPayload("ack");
+  requireString(payload.frameId, "ack.frameId");
+}
+
+function requireResumePayload(payload: unknown): void {
+  if (!isRecord(payload) || typeof payload.since !== "number" || !Number.isSafeInteger(payload.since) || payload.since < 0) {
+    throw invalidPayload("resume.since");
+  }
+}
+
+function requireString(value: unknown, field: string): void {
+  if (typeof value !== "string" || value.length === 0) throw invalidPayload(field);
+}
+
+function requireStringArray(value: unknown, field: string): void {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw invalidPayload(field);
+}
+
+function invalidPayload(field: string): BusProtocolError {
+  return new BusProtocolError("INVALID_PAYLOAD", `invalid ${field} payload`);
+}
+
+function isRole(value: unknown): value is BusRole {
+  return value === "provider" || value === "channel" || value === "orchestrator" || value === "integration";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/provider-base.ts

@@ -0,0 +1,101 @@
+import { RelayBusClient } from "./bus-client.js";
+import type { Message } from "./types.js";
+
+export interface ProviderAdapter {
+  readonly providerName: string;
+  readonly capabilities: string[];
+  deliverMessage(agentId: string, messages: Message[]): Promise<void>;
+  getAgentStatus(agentId: string): Promise<"idle" | "busy">;
+  spawn?(config: SpawnConfig): Promise<SpawnResult>;
+  shutdown?(agentId: string): Promise<void>;
+  formatDelivery?(messages: Message[]): string;
+}
+
+export interface SpawnConfig {
+  cwd: string;
+  label?: string;
+  approvalMode?: string;
+  prompt?: string;
+  env?: Record<string, string>;
+}
+
+export interface SpawnResult {
+  agentId: string;
+  pid?: number;
+  sessionId?: string;
+}
+
+export interface ProviderBaseOptions {
+  relayUrl: string;
+  adapter: ProviderAdapter;
+  agentId: string;
+  instanceId: string;
+  machine: string;
+  tags?: string[];
+  meta?: Record<string, unknown>;
+  token?: string;
+}
+
+export class ProviderBase {
+  readonly client: RelayBusClient;
+  private running = false;
+  private readonly pending = new Map<number, Message>();
+  private drain?: Timer;
+
+  constructor(private readonly options: ProviderBaseOptions) {
+    this.client = new RelayBusClient({
+      url: options.relayUrl,
+      role: "provider",
+      componentId: `${options.adapter.providerName}:${options.agentId}`,
+      agentId: options.agentId,
+      instanceId: options.instanceId,
+      token: options.token,
+      capabilities: options.adapter.capabilities,
+      tags: options.tags ?? [options.adapter.providerName],
+      machine: options.machine,
+      meta: { provider: options.adapter.providerName, ...(options.meta ?? {}) },
+    });
+  }
+
+  async run(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    this.client.on("message.new", (message) => this.queueMessage(message as Message));
+    await this.client.connect();
+    this.startStatusLoop();
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    if (this.drain) clearInterval(this.drain);
+    this.drain = undefined;
+    await this.client.close();
+  }
+
+  private queueMessage(message: Message): void {
+    if (message.to !== this.options.agentId && message.to !== "broadcast" && !message.to.startsWith("tag:") && !message.to.startsWith("cap:") && !message.to.startsWith("label:")) {
+      return;
+    }
+    this.pending.set(message.id, message);
+    void this.drainMessages();
+  }
+
+  private async drainMessages(): Promise<void> {
+    if (!this.running || this.pending.size === 0) return;
+    const messages = [...this.pending.values()].sort((a, b) => a.id - b.id);
+    this.pending.clear();
+    await this.options.adapter.deliverMessage(this.options.agentId, messages);
+  }
+
+  private startStatusLoop(): void {
+    this.drain = setInterval(async () => {
+      if (!this.running) return;
+      try {
+        const status = await this.options.adapter.getAgentStatus(this.options.agentId);
+        this.client.status({ agentStatus: status, ready: true });
+      } catch {
+        this.client.status({ agentStatus: "online", ready: false });
+      }
+    }, 30_000);
+  }
+}

package/src/reconnect.ts

@@ -0,0 +1,62 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+export interface ReconnectOptions {
+  initialMs: number;
+  maxMs: number;
+  jitterMs: number;
+}
+
+const DEFAULTS: ReconnectOptions = {
+  initialMs: 1000,
+  maxMs: 30_000,
+  jitterMs: 500,
+};
+
+export class ReconnectionManager {
+  private attempts = 0;
+  private abort?: AbortController;
+  private readonly options: ReconnectOptions;
+
+  constructor(options: Partial<ReconnectOptions> = {}) {
+    this.options = {
+      initialMs: options.initialMs ?? DEFAULTS.initialMs,
+      maxMs: options.maxMs ?? DEFAULTS.maxMs,
+      jitterMs: options.jitterMs ?? DEFAULTS.jitterMs,
+    };
+  }
+
+  get attempt(): number {
+    return this.attempts;
+  }
+
+  nextDelay(): number {
+    const base = Math.min(
+      this.options.maxMs,
+      this.options.initialMs * 2 ** this.attempts,
+    );
+    this.attempts += 1;
+    const jitter = this.options.jitterMs > 0
+      ? Math.floor(Math.random() * (this.options.jitterMs + 1))
+      : 0;
+    return Math.min(this.options.maxMs, base + jitter);
+  }
+
+  reset(): void {
+    this.attempts = 0;
+    this.cancel();
+  }
+
+  async schedule(): Promise<void> {
+    this.cancel();
+    this.abort = new AbortController();
+    const ms = this.nextDelay();
+    await delay(ms, undefined, { signal: this.abort.signal }).catch((error) => {
+      if ((error as { name?: string }).name !== "AbortError") throw error;
+    });
+  }
+
+  cancel(): void {
+    this.abort?.abort();
+    this.abort = undefined;
+  }
+}