npm-package-ws-has-241560546-weekly-downloads-but-sdk

Establishes a persistent WebSocket connection to a target URL and registers it in the stateful session registry. Returns a session_id for all subsequent operations. Use when an agent needs to initiate a long-lived connection before sending or receiving frames. Do NOT use to reconnect an already-open session -- call close_websocket_session first, or use the session_id of an existing session.

{
  "type": "object",
  "properties": {
    "target_url": {
      "description": "Full WebSocket URL to connect to (must start with ws:// or wss://).",
      "minLength": 6,
      "title": "Target Url",
      "type": "string"
    },
    "connect_timeout_seconds": {
      "default": 10,
      "description": "Maximum seconds to wait for the WebSocket handshake to complete.",
      "maximum": 60,
      "minimum": 0.5,
      "title": "Connect Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "target_url"
  ],
  "title": "open_websocket_sessionArguments"
}

Sends a single text or binary frame over an open session and returns the frame's Shannon entropy delta relative to the session baseline. Use for request-response patterns or publishing commands to a WebSocket server. Do NOT use to send a sequence of frames in bulk -- call this tool once per frame. Fails if session_id does not exist or connection is not in OPEN state.

{
  "type": "object",
  "properties": {
    "session_id": {
      "description": "32-character session id (uuid4 hex, no dashes) returned by open_websocket_session.",
      "maxLength": 32,
      "minLength": 32,
      "title": "Session Id",
      "type": "string"
    },
    "payload": {
      "description": "Frame payload. For binary frames, encode as hex and set frame_type to 'binary'.",
      "maxLength": 131072,
      "minLength": 0,
      "title": "Payload",
      "type": "string"
    },
    "frame_type": {
      "default": "text",
      "description": "Either 'text' or 'binary'. Determines wire encoding.",
      "enum": [
        "text",
        "binary"
      ],
      "title": "Frame Type",
      "type": "string"
    }
  },
  "required": [
    "session_id",
    "payload"
  ],
  "title": "send_typed_ws_frameArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "send_typed_ws_frameDictOutput"
}

Returns up to max_frames buffered inbound frames received since the last drain (or session open), each annotated with its Shannon entropy delta and schema validation result. Use to poll for incoming messages without holding a blocking connection. Do NOT use as a real-time streaming mechanism -- it returns only frames already buffered.

{
  "type": "object",
  "properties": {
    "session_id": {
      "description": "32-character session id of the open session to drain frames from.",
      "maxLength": 32,
      "minLength": 32,
      "title": "Session Id",
      "type": "string"
    },
    "max_frames": {
      "default": 32,
      "description": "Maximum number of buffered frames to return in a single call.",
      "maximum": 256,
      "minimum": 1,
      "title": "Max Frames",
      "type": "number"
    }
  },
  "required": [
    "session_id"
  ],
  "title": "drain_ws_frame_bufferArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "drain_ws_frame_bufferDictOutput"
}

Returns real-time telemetry for a session: connection state, frame counts, cumulative and rolling Shannon entropy statistics, schema violation rate, and uptime. Use to diagnose whether a stream is diverging from its expected schema or to verify a session is still alive before sending. Do NOT use as the primary liveness check in a tight loop.

{
  "type": "object",
  "properties": {
    "session_id": {
      "description": "32-character session id of the session to inspect.",
      "maxLength": 32,
      "minLength": 32,
      "title": "Session Id",
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "title": "inspect_ws_session_telemetryArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "inspect_ws_session_telemetryDictOutput"
}

Sends a WebSocket close frame with the specified status code, waits for the server close handshake, and removes the session from the registry. Returns a final telemetry snapshot. Use when a session is no longer needed. Do NOT use to temporarily pause a session -- the session_id is permanently deallocated after this call and cannot be reused.

{
  "type": "object",
  "properties": {
    "session_id": {
      "description": "32-character session id of the session to close.",
      "maxLength": 32,
      "minLength": 32,
      "title": "Session Id",
      "type": "string"
    },
    "status_code": {
      "default": 1000,
      "description": "WebSocket close status code per RFC 6455 (1000-4999). Defaults to 1000.",
      "maximum": 4999,
      "minimum": 1000,
      "title": "Status Code",
      "type": "number"
    },
    "reason": {
      "default": "",
      "description": "Optional UTF-8 close reason string, max 123 bytes per RFC 6455.",
      "maxLength": 123,
      "title": "Reason",
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "title": "close_websocket_sessionArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "close_websocket_sessionDictOutput"
}