agenticros 0.0.1 → 0.1.1

package/runtime/packages/core/src/transport/transport.ts

@@ -0,0 +1,77 @@
+import type {
+  ConnectionStatus,
+  ConnectionHandler,
+  Subscription,
+  PublishOptions,
+  AdvertiseOptions,
+  SubscribeOptions,
+  ServiceCallOptions,
+  ServiceCallResult,
+  ActionGoalOptions,
+  ActionResult,
+  TopicInfo,
+  ServiceInfo,
+  ActionInfo,
+  MessageHandler,
+} from "./types.js";
+
+/**
+ * Unified transport interface for ROS2 communication.
+ *
+ * All deployment modes (local DDS, rosbridge WebSocket, WebRTC data channel)
+ * implement this interface so that plugin tools work identically regardless
+ * of the underlying transport.
+ */
+export interface RosTransport {
+  // --- Connection lifecycle ---
+
+  /** Establish the transport connection. */
+  connect(): Promise<void>;
+
+  /** Gracefully close the transport connection. */
+  disconnect(): Promise<void>;
+
+  /** Get current connection status. */
+  getStatus(): ConnectionStatus;
+
+  /** Register a connection status change handler. Returns a cleanup function. */
+  onConnection(handler: ConnectionHandler): () => void;
+
+  // --- Topics ---
+
+  /** Optional: advertise topic with type (rosbridge uses this so publish works when topic not yet established). */
+  advertise?(options: AdvertiseOptions): void;
+
+  /** Publish a message to a ROS2 topic. May return a Promise so callers can await delivery (e.g. Zenoh put). */
+  publish(options: PublishOptions): void | Promise<void>;
+
+  /** Subscribe to a ROS2 topic. Returns a Subscription handle. */
+  subscribe(options: SubscribeOptions, handler: MessageHandler): Subscription;
+
+  /** Optional: async subscribe so the subscriber is declared before returning (Zenoh). Use when waiting for first message immediately. */
+  subscribeAsync?(options: SubscribeOptions, handler: MessageHandler): Promise<Subscription>;
+
+  // --- Services ---
+
+  /** Call a ROS2 service and return the result. */
+  callService(options: ServiceCallOptions): Promise<ServiceCallResult>;
+
+  // --- Actions ---
+
+  /** Send a goal to a ROS2 action server. */
+  sendActionGoal(options: ActionGoalOptions): Promise<ActionResult>;
+
+  /** Cancel an in-progress action goal. */
+  cancelActionGoal(action: string): Promise<void>;
+
+  // --- Introspection ---
+
+  /** List all available ROS2 topics. */
+  listTopics(): Promise<TopicInfo[]>;
+
+  /** List all available ROS2 services. */
+  listServices(): Promise<ServiceInfo[]>;
+
+  /** List all available ROS2 action servers. */
+  listActions(): Promise<ActionInfo[]>;
+}

package/runtime/packages/core/src/transport/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared types for the AgenticROS transport abstraction layer.
+ */
+
+// --- Connection ---
+
+export type ConnectionStatus = "disconnected" | "connecting" | "connected";
+
+export type MessageHandler = (msg: Record<string, unknown>) => void;
+
+export type ConnectionHandler = (status: ConnectionStatus) => void;
+
+/** Returned by subscribe(); call unsubscribe() to stop receiving messages. */
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+// --- Publish ---
+
+export interface PublishOptions {
+  topic: string;
+  type: string;
+  msg: Record<string, unknown>;
+}
+
+/** Optional: advertise a topic (type) before publishing. Used by rosbridge so the server creates the publisher with the right type. */
+export interface AdvertiseOptions {
+  topic: string;
+  type: string;
+}
+
+// --- Subscribe ---
+
+export interface SubscribeOptions {
+  topic: string;
+  type?: string;
+  throttleRate?: number;
+  queueLength?: number;
+}
+
+// --- Service Call ---
+
+export interface ServiceCallOptions {
+  service: string;
+  type?: string;
+  args?: Record<string, unknown>;
+}
+
+export interface ServiceCallResult {
+  result: boolean;
+  values?: Record<string, unknown>;
+}
+
+// --- Action ---
+
+export interface ActionGoalOptions {
+  action: string;
+  actionType: string;
+  args?: Record<string, unknown>;
+  onFeedback?: (feedback: Record<string, unknown>) => void;
+}
+
+export interface ActionResult {
+  result: boolean;
+  values?: Record<string, unknown>;
+}
+
+// --- Introspection ---
+
+export interface TopicInfo {
+  name: string;
+  type: string;
+}
+
+export interface ServiceInfo {
+  name: string;
+  type: string;
+}
+
+export interface ActionInfo {
+  name: string;
+  type: string;
+}
+
+// --- Transport Configuration ---
+
+export interface RosbridgeTransportConfig {
+  mode: "rosbridge";
+  rosbridge: {
+    url: string;
+    reconnect?: boolean;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+  };
+}
+
+export interface LocalTransportConfig {
+  mode: "local";
+  local?: {
+    domainId?: number;
+  };
+}
+
+export interface WebRTCTransportConfig {
+  mode: "webrtc";
+  webrtc: {
+    signalingUrl: string;
+    apiUrl: string;
+    robotId: string;
+    robotKey: string;
+    iceServers?: RTCIceServerConfig[];
+  };
+}
+
+export interface ZenohTransportConfig {
+  mode: "zenoh";
+  zenoh: {
+    routerEndpoint: string;
+    domainId?: number;
+    keyFormat?: "ros2dds" | "rmw_zenoh";
+    /** Matches zenoh-bridge-ros2dds ros2dds.namespace when not default "/". */
+    bridgeNamespace?: string;
+  };
+}
+
+export interface RTCIceServerConfig {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+/** Discriminated union of all transport configurations. */
+export type TransportConfig =
+  | RosbridgeTransportConfig
+  | LocalTransportConfig
+  | WebRTCTransportConfig
+  | ZenohTransportConfig;

package/runtime/packages/core/src/transport/webrtc/signaling-client.ts

@@ -0,0 +1,196 @@
+import WebSocket from "ws";
+import type {
+  ConnectRequest,
+  ConnectResponse,
+  DisconnectResponse,
+  DiscoverResponse,
+  SignalingMessage,
+  JoinRoomMessage,
+  AnswerMessage,
+  IceCandidateMessage,
+  HeartbeatMessage,
+} from "./signaling-types.js";
+
+export type SignalingMessageHandler = (msg: SignalingMessage) => void;
+
+/**
+ * Client for the WebRTC signaling server.
+ *
+ * Encapsulates REST API calls (discover, connect, disconnect) and
+ * WebSocket lifecycle (connect, send, message routing, heartbeat).
+ */
+export class SignalingClient {
+  private ws: WebSocket | null = null;
+  private apiUrl: string;
+  private signalingUrl: string;
+  private messageHandler: SignalingMessageHandler | null = null;
+  private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(apiUrl: string, signalingUrl: string) {
+    // Normalize: strip trailing slashes
+    this.apiUrl = apiUrl.replace(/\/+$/, "");
+    this.signalingUrl = signalingUrl.replace(/\/+$/, "");
+  }
+
+  // --- REST API ---
+
+  async discoverRobots(): Promise<DiscoverResponse> {
+    const res = await fetch(`${this.apiUrl}/api/robots/`);
+    if (!res.ok) {
+      throw new Error(`Discovery failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<DiscoverResponse>;
+  }
+
+  async requestConnection(robotId: string, request: ConnectRequest): Promise<ConnectResponse> {
+    const res = await fetch(`${this.apiUrl}/api/robots/${robotId}/connect`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Connection request failed: ${res.status} — ${body}`);
+    }
+    return res.json() as Promise<ConnectResponse>;
+  }
+
+  async requestDisconnect(robotId: string): Promise<DisconnectResponse> {
+    const res = await fetch(`${this.apiUrl}/api/robots/${robotId}/disconnect`, {
+      method: "POST",
+    });
+    if (!res.ok) {
+      throw new Error(`Disconnect request failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<DisconnectResponse>;
+  }
+
+  // --- WebSocket ---
+
+  /** Connect to the signaling WebSocket server. */
+  async connectWs(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const wsUrl = `${this.signalingUrl}/ws`;
+      const timeout = setTimeout(() => {
+        reject(new Error(`Signaling WebSocket connection to ${wsUrl} timed out`));
+      }, 10_000);
+
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.onopen = () => {
+        clearTimeout(timeout);
+        this.startHeartbeat();
+        resolve();
+      };
+
+      this.ws.onmessage = (event) => {
+        const data = typeof event.data === "string" ? event.data : event.data.toString();
+        let msg: SignalingMessage;
+        try {
+          msg = JSON.parse(data) as SignalingMessage;
+        } catch {
+          return;
+        }
+
+        // Auto-respond to heartbeat requests
+        if (msg.type === "heartbeat_request") {
+          this.send({ type: "heartbeat", timestamp: Date.now() } satisfies HeartbeatMessage);
+          return;
+        }
+
+        if (this.messageHandler) {
+          this.messageHandler(msg);
+        }
+      };
+
+      this.ws.onerror = () => {
+        clearTimeout(timeout);
+        reject(new Error(`Signaling WebSocket error connecting to ${wsUrl}`));
+      };
+
+      this.ws.onclose = () => {
+        clearTimeout(timeout);
+        this.stopHeartbeat();
+        this.ws = null;
+      };
+    });
+  }
+
+  /** Set the handler for incoming signaling messages. */
+  onMessage(handler: SignalingMessageHandler): void {
+    this.messageHandler = handler;
+  }
+
+  /** Send a signaling message over WebSocket. */
+  send(message: SignalingMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("Signaling WebSocket is not connected");
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+
+  /** Send join_room to enter the session room. */
+  joinRoom(roomId: string, peerId: string, peerType: "frontend" | "robot", sessionId: string): void {
+    this.send({
+      type: "join_room",
+      room_id: roomId,
+      peer_id: peerId,
+      peer_type: peerType,
+      session_id: sessionId,
+    } satisfies JoinRoomMessage);
+  }
+
+  /** Send an SDP answer back to the peer. */
+  sendAnswer(sdp: string, roomId: string, peerId: string, targetPeerId?: string): void {
+    this.send({
+      type: "answer",
+      data: { type: "answer", sdp },
+      room_id: roomId,
+      peer_id: peerId,
+      target_peer_id: targetPeerId,
+    } satisfies AnswerMessage);
+  }
+
+  /** Send an ICE candidate to the peer. */
+  sendIceCandidate(candidate: string, sdpMid: string | null, sdpMLineIndex: number | null, targetPeerId?: string): void {
+    this.send({
+      type: "ice_candidate",
+      data: {
+        candidate,
+        sdpMid,
+        sdpMLineIndex,
+      },
+      target_peer_id: targetPeerId,
+    } satisfies IceCandidateMessage);
+  }
+
+  /** Close the signaling WebSocket. */
+  close(): void {
+    this.stopHeartbeat();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /** Whether the WebSocket is currently connected. */
+  get isConnected(): boolean {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatInterval = setInterval(() => {
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        this.send({ type: "heartbeat", timestamp: Date.now() } satisfies HeartbeatMessage);
+      }
+    }, 15_000);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+}

package/runtime/packages/core/src/transport/webrtc/signaling-types.ts

@@ -0,0 +1,130 @@
+/**
+ * Type definitions for the WebRTC signaling server protocol.
+ *
+ * These match the message format used by the webrtc-py signaling server
+ * (see mock_client.py and mock_robot.py for reference implementations).
+ */
+
+// --- REST API ---
+
+export interface ConnectRequest {
+  user_id: string;
+  robot_id: string;
+  robot_key: string;
+}
+
+export interface ConnectResponse {
+  session: { session_id: string };
+  room_id: string;
+}
+
+export interface DisconnectResponse {
+  status: string;
+}
+
+export interface RobotInfo {
+  robot_id: string;
+  status: string;
+  capabilities?: string[];
+}
+
+export type DiscoverResponse = RobotInfo[];
+
+// --- WebSocket signaling messages ---
+
+/** Base shape for all signaling messages. */
+export interface SignalingMessage {
+  type: string;
+  [key: string]: unknown;
+}
+
+// Client → Server
+
+export interface JoinRoomMessage extends SignalingMessage {
+  type: "join_room";
+  room_id: string;
+  peer_id: string;
+  peer_type: "frontend" | "robot";
+  session_id: string;
+}
+
+export interface RobotConnectMessage extends SignalingMessage {
+  type: "robot_connect";
+  robot_token: string;
+  robot_id: string;
+  capabilities?: string[];
+}
+
+export interface SessionAcceptedMessage extends SignalingMessage {
+  type: "session_accepted";
+  session_id: string;
+  robot_id: string;
+}
+
+export interface OfferMessage extends SignalingMessage {
+  type: "offer";
+  data: { type: string; sdp: string };
+  from_peer_id?: string;
+  target_peer_id?: string;
+}
+
+export interface AnswerMessage extends SignalingMessage {
+  type: "answer";
+  data: { type: string; sdp: string };
+  room_id?: string;
+  peer_id?: string;
+  target_peer_id?: string;
+}
+
+export interface IceCandidateMessage extends SignalingMessage {
+  type: "ice_candidate";
+  data: {
+    candidate: string;
+    sdpMid: string | null;
+    sdpMLineIndex: number | null;
+  };
+  target_peer_id?: string;
+}
+
+export interface HeartbeatMessage extends SignalingMessage {
+  type: "heartbeat";
+  timestamp: number;
+}
+
+// Server → Client
+
+export interface PeerJoinedMessage extends SignalingMessage {
+  type: "peer_joined";
+  peer_id: string;
+  peer_type: "frontend" | "robot";
+}
+
+export interface PeerLeftMessage extends SignalingMessage {
+  type: "peer_left";
+  peer_id: string;
+}
+
+export interface SessionInvitationMessage extends SignalingMessage {
+  type: "session_invitation";
+  session_id: string;
+  room_id: string;
+  robot_key: string;
+  user_id: string;
+}
+
+export interface SessionEndedMessage extends SignalingMessage {
+  type: "session_ended";
+  session_id: string;
+  reason?: string;
+}
+
+export interface HeartbeatRequestMessage extends SignalingMessage {
+  type: "heartbeat_request";
+  timestamp: number;
+}
+
+export interface ErrorMessage extends SignalingMessage {
+  type: "error";
+  message: string;
+  code?: string;
+}